# APS — Adeno Package Service

**aps.adeno.ltd** — the package registry and URA distribution path for the Adeno platform. Athena can also front the same service at `athena.adeno.ltd/aps`.

APS hosts `.aps` solution packages, Uracil `.ura` binaries, and device-authenticated admin workflows. Packages are ZIP archives containing a `manifest.json` and solution code.

## Components

- **Backend** (`api/`): FastAPI service for package listing, device auth, uploads, and URA distribution
- **CLI** (`cli/`): the `aps` command-line tool for login, install, upload, audit, and package management

## Package styles

APS supports two package styles:

- **Python packages** with `entry_point` and optional `dependencies`
- **Uracil service bundles** with `runtime`, `service`, and `permissions` sections

## API endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/device/start` | Start a device-style APS login flow |
| GET | `/api/auth/device/{session_id}` | Poll device auth status and retrieve token after approval |
| GET | `/api/packages` | List all packages |
| GET | `/api/packages/{name}` | Get package metadata |
| GET | `/api/packages/{name}/{version}` | Download a specific version |
| POST | `/api/packages` | Upload a new package (admin token required) |
| DELETE | `/api/packages/{name}/{version}` | Remove a package version (admin token required) |

## APS format

```
solution.aps (ZIP)
├── manifest.json       # package contract
├── main.py             # python entry point (legacy python packages)
├── functions/          # uracil function snippets
│   ├── *.py
│   └── *.cpp
└── lib/                # additional modules/helpers
```

### Python package manifest

```json
{
	"name": "weather-check",
	"version": "0.1.0",
	"description": "Example APS python package",
	"entry_point": "main.py",
	"dependencies": ["httpx"]
}
```

### Uracil service manifest

```json
{
	"name": "weather-check-service",
	"version": "0.1.0",
	"description": "Example APS Uracil service package",
	"runtime": {
		"name": "uracil",
		"abi": "uracil.service.v1",
		"mode": "rootless",
		"hotswap_group": "weather-check-service",
		"payload_revision": "0.1.0",
		"target_env": "keryx-ami"
	},
	"security": {
		"cauth": {
			"enabled": true,
			"mode": "adeno-cauth",
			"base_url": "https://adeno.ltd/cauth",
			"issuer": "https://adeno.ltd/cauth",
			"audience": "keryx",
			"token_env": "KERYX_TRANSTOKEN",
			"secret_key_env": "CAUTH_SECRET_KEY",
			"encryption_key_env": "CAUTH_ENCRYPTION_KEY"
		}
	},
	"service": {
		"entry_function": "current-weather",
		"functions": [
			{
				"name": "current-weather",
				"description": "Fetch the current weather for a city.",
				"snippet_path": "functions/current_weather.py",
				"required_permissions": ["net.client"]
			},
			{
				"name": "current-weather-fast",
				"description": "Native C++ fast path for API-heavy weather checks.",
				"snippet_path": "functions/current_weather.cpp",
				"language": "cpp",
				"build": { "standard": "c++20", "flags": ["-O3"] },
				"required_permissions": ["net.client"]
			}
		]
	},
	"permissions": {
		"requested": ["net.client"]
	},
	"runner": {
		"kind": "gguf-http",
		"protocol": "http",
		"bind": "127.0.0.1:8088",
		"model": {
			"format": "gguf",
			"uri": "corpus://athena/models/weather-check.gguf"
		}
	}
}
```

Uracil service functions can be authored as Python or native C++. For native functions, set `language` to `cpp`. The APS host runtime compiles them on demand for dynamic packages, and `ura_builder.py` embeds the compiled binary into `.ura` artifacts for target environments such as the Keryx AMI.

When `security.cauth` is present, APS and Uracil project the CAuth contract into `URACIL_CAUTH_*` environment variables so service bundles can participate in Adeno-authenticated encrypted flows without hard-coding deployment secrets into the manifest.

## CLI

The CLI defaults to `https://aps.adeno.ltd`. Set `APS_REGISTRY=https://athena.adeno.ltd/aps` to route package operations through Athena.

```bash
aps login
aps login --admin
aps install weather-check
aps install service weather-check-service
aps upload dist/weather-check-service.aps
aps audit weather-check-service
aps audit weather-check-service --shell
aps permissions weather-check-service
aps grant weather-check-service net.client
aps run weather-check-service --function current-weather London
```

## Admin flow

1. Run `aps login --admin`.
2. Open the auth URL returned by the service.
3. Approve the request in the hosted login page.
4. Use the stored token for `aps upload` and other admin-gated operations.

## Relationship to Uracil

APS is the distribution channel; [Uracil](/products/uracil/) is the runtime. A typical loop: publish an `.aps` bundle → `aps install service <name>` on the target → `uracil --bundle ~/.aps/packages/<name> grant <perm>` → `uracil --bundle ... run <function>`. Athena packages model-backed services as APS bundles first, then compiles them into `.ura` binaries carrying GGUF runner metadata.