Skip to content

Store

The Store is a core Directory component that persists agent records as OCI artifacts in a registry-backed content store.

Role in the system

When a client pushes a record, the server:

  1. Validates the record against the OASF schema.
  2. Writes the payload to the configured OCI registry.
  3. Derives a content identifier (CID) from the artifact digest for immutable, content-addressed lookup.

Records can be retrieved by CID or, when configured with a verifiable name, by Docker-style name references (name, name:version, name:version@cid).

Backends and configuration

Directory supports multiple OCI-compatible registry backends:

Registry Type Description
zot Zot OCI registry (default for local deployments)
ghcr GitHub Container Registry
dockerhub Docker Hub

The backend is configured via environment variables on the Directory server:

Environment Variable Description Default
DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS Registry address 127.0.0.1:5000
DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME Repository name dir

Credentials are supplied through additional environment variables:

Environment Variable Description
DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME Username for basic authentication
DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD Password for basic authentication
DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_ACCESS_TOKEN Access token for token-based authentication
DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE Skip TLS verification (default: true)

Configuration examples

Zot (local development)

export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=localhost:5000
export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=dir
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=true

GitHub Container Registry (GHCR)

export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=ghcr.io
export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=your-org/dir
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME=your-github-username
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD=your-github-token
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=false

Warning

GHCR does not support record deletion via the OCI API. Attempting to delete a record when using GHCR will return an error. To manage packages hosted on GHCR, use the GitHub UI, REST API, or GraphQL API instead. See Deleting and restoring a package for details.

Docker Hub

export DIRECTORY_SERVER_STORE_OCI_REGISTRY_ADDRESS=docker.io
export DIRECTORY_SERVER_STORE_OCI_REPOSITORY_NAME=your-username/dir
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_USERNAME=your-dockerhub-username
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_PASSWORD=your-dockerhub-token
export DIRECTORY_SERVER_STORE_OCI_AUTH_CONFIG_INSECURE=false

See also Local Deployment and Production Deployment for deployment-specific configuration.

Storage model

ADS differs from block storage systems like IPFS in its approach to distributed object storage:

  • Simplified content retrieval — ADS stores complete records rather than splitting them into blocks, so no special optimizations are needed to reassemble content from multiple sources. Records are retrieved as complete units using standard OCI protocols.
  • OCI integration — records are stored and transferred as OCI artifacts, so any OCI distribution-compliant server can participate in the network and peers retrieve records directly from each other using standard OCI protocols.

While ADS uses zot as its reference OCI server implementation, the system works with any server that implements the OCI distribution specification.