Registry

The registry is a local-first, OCI-distributable system for managing agent configurations, secrets, and parameters. It is backed by TinyDB for local persistence and ORAS for OCI artifact distribution.

Storage layout

$ALQUIMIA_REGISTRY_DIR/          (default: ~/.local/share/alquimia)
├── metadata.json                 # All agentspace metadata
├── <agentspace-id>/
│   └── dist.json                 # Agents, secrets, parameters (TinyDB)
└── history/                      # Persisted local sessions
    └── <session-id>

AlquimiaRegistry

from alquimia.registry.registry import AlquimiaRegistry

registry = AlquimiaRegistry()

Loading an agentspace

registry.load({"agentspace_id": "default"})
# registry.current_agentspace is now set

Agentspace operations

Method	Description
`create(metadata)`	Create a new agentspace
`load(selector)`	Load an agentspace by selector
`save(data)`	Update agentspace metadata
`destroy()`	Delete the agentspace and all data
`list_repos()`	List all agentspaces
`query_repos(filters)`	Filter agentspaces by TinyDB predicates

Agent operations

Method	Description
`add_agent(spec)`	Upsert an agent specification
`get_agent(assistant_id)`	Get a single agent by ID
`list_agents()`	List all agents in the current agentspace
`query_agents(selector)`	Filter agents by TinyDB predicates
`delete_agents(filters)`	Delete agents matching filters

Secret operations

Method	Description
`add_secret(secret)`	Register a secret definition
`list_secrets()`	List all secrets
`query_secrets(filters)`	Filter secrets
`delete_secrets(filters)`	Delete secrets matching filters

Parameter operations

Method	Description
`add_parameters(param_def)`	Register parameter definitions
`list_parameters()`	List all parameters
`query_parameters(filters)`	Filter parameters
`delete_parameters(filters)`	Delete parameters matching filters

OCI operations

Method	Description
`push(tag, **annotations)`	Publish agentspace to OCI registry
`pull(source_repo_id)`	Fetch agentspace from OCI registry
`delete_manifest(tag)`	Remove a published manifest

Secrets

Secrets are referenced in agent specs with $secretRef markers:

{ "api_key": { "$secretRef": "OPENAI_API_KEY" } }

Secret model

class Secret(BaseModel):
    key: str           # The secret key name
    scope: str         # "global", "shared", or "local"
    description: str | None = None

Resolvers

Resolver	`ALQUIMIA_REGISTRY_SECRET_RESOLVER`	Backend
`EnvSecretResolver`	`env` (default)	Environment variables
`VaultSecretResolver`	`vault`	HashiCorp Vault KV v2

Scoping

Scope	Key pattern	Example
`global`	`{KEY}`	`OPENAI_API_KEY`
`shared`	`{realm}_{KEY}`	`abc123_OPENAI_API_KEY`
`local`	`{realm}_{assistant_id}_{KEY}`	`abc123_mybot_OPENAI_API_KEY`

OCI distribution

Agent configurations are distributed as OCI artifacts:

Artifact type: application/vnd.alquimia.registry.v1
Layer media type: application/vnd.alquimia.registry.dist.v1+json

# Publish
alquimia registry publish --agentspace-id default --tag v1.0.0

# Pull
alquimia registry fetch --agentspace-id default --source ghcr.io/myorg/my-agents:v1.0.0

Encryption at rest

Registry data is encrypted at rest when ALQUIMIA_REGISTRY_KEY is set (added in 0.3.2). The storage layer uses AES-256-GCM via the cryptography library.

Feature	Description
Algorithm	AES-256-GCM
Key source	`ALQUIMIA_REGISTRY_KEY` (base64-encoded 32-byte key)
Key ID	`ALQUIMIA_REGISTRY_KEY_ID` (stored in envelope for key rotation)
Format	JSON envelope: `{"_enc": {"v": 1, "kid": "...", "nonce": "...", "ct": "..."}}`
Fallback	If `ALQUIMIA_REGISTRY_KEY` is absent, storage operates in plaintext mode (backward compatible)

Existing unencrypted registries remain readable. New writes become encrypted as soon as ALQUIMIA_REGISTRY_KEY is configured.

# Generate a key
python -c "import base64, secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"

export ALQUIMIA_REGISTRY_KEY="<base64-encoded-32-byte-key>"
export ALQUIMIA_REGISTRY_KEY_ID="key-2024-01"

Environment variables

Variable	Default	Description
`ALQUIMIA_REGISTRY_DIR`	`~/.local/share/alquimia`	Local registry storage directory
`ALQUIMIA_LOCAL_SESSIONS_DIR`	`$ALQUIMIA_REGISTRY_DIR/history`	Session persistence directory
`ALQUIMIA_REGISTRY_SECRET_RESOLVER`	`env`	Secret resolver backend
`ALQUIMIA_OCI_REGISTRY_DEFAULT`	`ghcr.io`	Default OCI registry
`ALQUIMIA_REGISTRY_KEY`	`null`	AES-256-GCM encryption key (base64-encoded 32-byte)
`ALQUIMIA_REGISTRY_KEY_ID`	`null`	Key ID for key rotation tracking
`ORAS_PLAIN_HTTP`	`false`	Use plain HTTP for ORAS
`ORAS_INSECURE`	`false`	Skip TLS verification
`VAULT_ADDR`	—	Vault server URL
`VAULT_TOKEN`	—	Vault authentication token
`VAULT_MOUNT_POINT`	`secret`	Vault KV v2 mount point

CLI — registry management commands
Runtime Registry API — HTTP API for registry operations

Source

Alquimia-ai/alquimia-core — src/alquimia/registry/registry.py, src/alquimia/registry/repo.py, src/alquimia/registry/secret.py