Publish and pull an agentspace

Agentspaces can be packaged as OCI artifacts, signed with cosign, and promoted through environments the same way you promote container images. This guide walks through publishing an agentspace and pulling it into another runtime.

Before you begin

Install alquimia-core[registry].
Have access to an OCI registry (GHCR, Docker Hub, ECR, Harbor, or a private ORAS registry).
Optionally install cosign if you want signed artifacts.

Publish an agentspace

Create or load the agentspace locally.

alquimia registry create --name production
alquimia registry agents add support-bot.json --namespace production

(Recommended) classify tools and topics before publishing.

Unsigned, unclassified tools are denied under the default Zero Trust policy when the agentspace is pulled into a production runtime.

alquimia registry tools add filesystem-tools \
  --provider-id mcp \
  --connection-config '{"url": {"$secretRef": "FILESYSTEM_MCP_URL"}}'

alquimia registry tools set-operation filesystem-tools "list_*" \
  --match glob --severity read-only --tier-grants reader,editor,operator

Publish to the OCI registry.
Terminal window
```
alquimia registry publish --namespace production \
  --oci-reference ghcr.io/acme/alquimia/production \
  --tag v1.0.0
```
Add --include-secrets to also publish secret metadata (key, scope, dtype, required). Secret values are never included.

Verify the manifest in the registry.

alquimia explore tags \
  --repository ghcr.io/acme/alquimia/production

Sign artifacts with cosign

If cosign is installed and ALQUIMIA_OCI_COSIGN_KEY is set, publish signs the artifact automatically. For keyless signing, set the certificate identity and issuer instead:

export ALQUIMIA_OCI_COSIGN_CERT_IDENTITY=alice@acme.com
export ALQUIMIA_OCI_COSIGN_CERT_OIDC_ISSUER=https://accounts.google.com

The signature is verified on every pull according to ALQUIMIA_OCI_SIGNATURE_POLICY:

Policy	Behaviour
`required` (default)	Abort on missing or invalid signature
`warn`	Log a warning and continue on failure
`off`	Skip verification

Pull an agentspace

On the target runtime:

Authenticate to the registry if needed (oras/docker login).

Set the signature verification policy.

export ALQUIMIA_OCI_SIGNATURE_POLICY=required
export ALQUIMIA_OCI_COSIGN_KEY=/etc/alquimia/cosign.pub

Pull the artifact.
Terminal window
```
alquimia registry pull --namespace production \
  --oci-reference ghcr.io/acme/alquimia/production \
  --tag v1.0.0
```
Pulling rehydrates local knowledge bases from the file registrations contained in the artifact.

Encrypted local registries

If ALQUIMIA_REGISTRY_KEY is set on the source runtime, the local TinyDB files stay encrypted. The OCI artifact itself is published as plaintext JSON so the target runtime does not need your AES key to consume it. The target runtime can encrypt its own local copy with a different key if desired.

Promoting through environments

A typical promotion flow looks like this:

dev agentspace  ──publish──►  ghcr.io/acme/alquimia/production:v1.0.0-dev
                                    │
                                    ▼
staging agentspace ◄──pull──  validate / test
                                    │
                                    ▼
production agentspace ◄──pull──  approve and tag v1.0.0

Use immutable tags for releases and keep a latest tag only for development. Record the OCI digest in your change-management system so audits can correlate a running agent to the exact artifact it came from.

Troubleshooting

Symptom	Cause	Fix
`signature verification failed`	Cosign key mismatch or missing signature	Verify the correct public key or set policy to `warn` only in dev
`manifest schema version mismatch`	Artifact was not produced by Alquimia Platform	Check the registry repository and tag
`unrecognized media type`	Layer from a newer/older Alquimia Platform version	Upgrade or downgrade `alquimia-core` to match
`pull refused: local registry is read-only`	Worker pod cannot write	Run `pull` on a master instance or set `ALQUIMIA_RUNTIME_MODE=master`