Registry & OCI distribution

The Alquimia Platform registry is a local TinyDB store that holds agent specs, secrets, parameters, tool registrations, knowledge topics, file registrations, and model registrations. Each agentspace maps to a directory on disk and can be packaged as a signed OCI artifact for promotion between environments.

What the registry stores

Table	Holds
`agents`	`AssistantConfig` JSON documents
`secrets`	Secret definitions (name, scope, dtype, required) — never values
`parameters`	`ParameterDef` values for parameterized agents
`tools`	`ToolRegistration` connection config and per-operation classification
`topics`	`TopicRegistration` bindings to vector-store collections
`files`	`FileRegistration` metadata for topic files
`models`	`ModelRegistration` for reusable LLM connectors

Secrets are stored as references only. Values are resolved at inference time from environment variables or HashiCorp Vault.

Local layout

$ALQUIMIA_REGISTRY_DIR/
├── metadata.json          # agentspace metadata
└── <agentspace_id>/
    └── dist.json          # agents, tools, topics, files, models, secret defs

Set ALQUIMIA_REGISTRY_DIR to change the storage root. In production the registry volume is mounted read/write on the master and read-only on workers (ALQUIMIA_RUNTIME_MODE=worker).

Encryption at rest

Set ALQUIMIA_REGISTRY_KEY to enable transparent AES-256-GCM encryption of all TinyDB JSON files. The key is a Base64-encoded AES-256 key, typically sourced from Vault.

Encryption protects against volume or bucket exposure.
It does not protect against a compromised runtime process, which can read decrypted data through normal registry APIs.
Use ALQUIMIA_RUNTIME_MODE=worker for inference pods so the registry is read-only.
The ciphertext envelope stores a kid field from ALQUIMIA_REGISTRY_KEY_ID (default default) for key rotation.
If ALQUIMIA_REGISTRY_KEY is absent, the registry stores plaintext for backward compatibility.

OCI distribution

Agentspaces can be published to and pulled from any OCI registry (Docker Hub, GHCR, ECR, a private ORAS registry, etc.). The registry uses the ORAS CLI under the hood.

Layer media types

Media type	Content	Included by default
`application/vnd.alquimia.registry.dist.v1+json`	Complete `dist.json`	Yes
`application/vnd.alquimia.registry.dist.public.v1+json`	Public layer (legacy)	Pull only
`application/vnd.alquimia.registry.dist.private.v1+json`	Private layer (legacy)	Pull only

By default the secrets table is excluded from pushes. Pass --include-secrets to also push secret metadata (key, scope, dtype, required — never values) as a separate dist.private.json layer. The public layer becomes dist.public.json. Pulling reassembles both layers back into a single local dist.json.

Encrypted-registry push behavior

If the local dist.json is encrypted, push() creates temporary plaintext copies for the OCI layers. The remote artifact is standard, unencrypted JSON so external consumers can read it without your AES key. The local file stays encrypted and temporary plaintext files are deleted after the ORAS transfer.

Manifest validation

Every pull() validates the OCI manifest before downloading blobs:

schemaVersion must be 2.
annotations["ai.alquimia.registry.dist.schema"] (if present) must equal https://alquimia.ai/schema/dist+v1.
annotations["ai.alquimia.registry.dist.version"] (if present) must equal v1.
Every layer must carry a recognized Alquimia Platform media type.

Mismatched schema versions or unrecognized layer types raise an error immediately.

Signature verification

OCI artifacts can be signed and verified with cosign.

Variable	Default	Description
`ALQUIMIA_OCI_SIGNATURE_POLICY`	`required`	`required`, `warn`, or `off`
`ALQUIMIA_OCI_COSIGN_KEY`	—	Path to a cosign public/private key file
`ALQUIMIA_OCI_COSIGN_CERT_IDENTITY`	—	Keyless verification certificate identity
`ALQUIMIA_OCI_COSIGN_CERT_OIDC_ISSUER`	—	Keyless verification OIDC issuer

required aborts if cosign is missing or the signature is invalid.
warn logs a warning and continues on verification failure.
off skips verification entirely.

push() signs the artifact automatically when cosign is available and configured.

Dev-mode transport

Insecure ORAS flags are gated behind ALQUIMIA_OCI_DEV_MODE=true to prevent accidental use in production:

Variable	Default	Effect when dev mode is on
`ORAS_PLAIN_HTTP`	`false`	Appends `--plain-http`
`ORAS_INSECURE`	`false`	Appends `--insecure`

If either flag is set while dev mode is off, a warning is emitted and the flag is ignored.

Runtime mode and registry access

Mode	Registry access	Purpose
`master`	Read/write	Serves the API and mutates the registry
`worker`	Read-only	Consumes Kafka events and runs inference
`all`	Read/write	Single-process local development

Run workers as separate pods with the registry mounted read-only so a compromised inference workload cannot alter agent specs, tool registrations, or topic metadata.

Common operational commands

# Create an agentspace
alquimia registry create --name myspace

# Publish an agentspace to OCI
alquimia registry publish --namespace myspace \
  --oci-reference ghcr.io/acme/alquimia/myspace \
  --tag v1.2.0

# Pull an agentspace from OCI
alquimia registry pull --namespace myspace \
  --oci-reference ghcr.io/acme/alquimia/myspace \
  --tag v1.2.0

# Explore available artifacts
alquimia explore repos --registry ghcr.io/acme/alquimia
alquimia explore tags --repository ghcr.io/acme/alquimia/myspace

See Publish and pull an agentspace for a step-by-step guide.