Artifact Storage

Configure where ElasticClaw Server stores hub-owned artifacts such as checkpoint payloads, future volumes, and other large non-Git data.

Overview

Artifact storage is the hub-owned storage layer for data that should not live in GitHub. ElasticClaw uses content-addressed blobs, manifests, and refs so higher-level features can store structured artifacts without depending on a specific storage backend.

The first supported backends are local filesystem storage and S3-compatible object storage. Checkpoints and volumes can build on the same artifact store, while the database keeps metadata, permissions, leases, and retention policy.

Default local storage

If artifact_storage is omitted, ElasticClaw Server uses a local filesystem store under the hub data directory.

text

~/.elasticclaw/
  hub.yaml
  hub.db
  artifacts/
    blobs/
    manifests/
    refs/

System installs that use /etc/elasticclaw/hub.yaml store hub data under /var/lib/elasticclaw, so the default artifact path is /var/lib/elasticclaw/artifacts.

Custom local path

Use a local backend with an explicit path when you want artifacts on a larger disk, mounted filesystem, or backup-managed directory.

yaml

artifact_storage:
  backend: local
  local:
    path: /var/lib/elasticclaw/artifacts

The hub process must be able to create directories and read/write files at this path. Local storage is simplest for single-node deployments.

S3-compatible storage

Use the s3 backend to store artifact blobs, manifests, and refs in AWS S3 or an S3-compatible service such as MinIO, Cloudflare R2, or another object store.

yaml

artifact_storage:
  backend: s3
  s3:
    bucket: elasticclaw-artifacts
    region: us-east-1
    prefix: production
    access_key_id: ${ELASTICCLAW_ARTIFACTS_ACCESS_KEY_ID}
    secret_access_key: ${ELASTICCLAW_ARTIFACTS_SECRET_ACCESS_KEY}

The prefix is optional. Use it to isolate environments inside one bucket, for example dev, staging, or production.

S3-compatible endpoint

For non-AWS object stores, set endpoint and usually path_style: true.

yaml

artifact_storage:
  backend: s3
  s3:
    bucket: elasticclaw
    region: us-east-1
    endpoint: https://minio.example.com
    prefix: hub
    path_style: true
    access_key_id: ${MINIO_ACCESS_KEY_ID}
    secret_access_key: ${MINIO_SECRET_ACCESS_KEY}

Keep artifact credentials scoped to the configured bucket and prefix when your object store supports it.

Configuration fields

artifact_storage.backendStorage backend. Use local or s3. Defaults to local.

artifact_storage.local.pathFilesystem path for local artifact storage. Defaults to <hub data dir>/artifacts.

artifact_storage.s3.bucketS3 bucket name for artifact objects.

artifact_storage.s3.regionS3 region. Defaults to us-east-1 when omitted.

artifact_storage.s3.endpointOptional S3-compatible endpoint URL for non-AWS object stores.

artifact_storage.s3.prefixOptional object key prefix used to isolate environments or hubs.

artifact_storage.s3.access_key_idAccess key ID. Can reference an environment variable with ${...}.

artifact_storage.s3.secret_access_keySecret access key. Can reference an environment variable with ${...}.

artifact_storage.s3.session_tokenOptional session token for temporary credentials.

artifact_storage.s3.path_styleUse path-style bucket URLs. Commonly required by S3-compatible stores.

Operational notes

Artifact storage is not a Git remote. Agents only see this data when higher-level features, such as checkpoints or volumes, explicitly use it.
The hub database remains the control plane for metadata. The artifact store holds the large content blobs, manifests, and refs.
Back up both the hub database and artifact storage. Refs and blobs are useful only when the hub metadata still points at them.