Workflow Volumes

Attach hub-managed artifact-backed directories to workflow agents for non-Git data that should persist across runs.

Overview

Workflow volumes let a workflow mount data that belongs to the hub instead of the Git repository. Use volumes for caches, downloaded datasets, generated indexes, model artifacts, or other files that an agent needs during a run but should not commit to GitHub.

Volumes are stored through ElasticClaw artifact storage. The hub keeps lease metadata in the database, while the artifact store holds the archived directory contents. Configure artifact storage with local or S3-compatible storage before relying on volumes for durable data.

Workflow configuration

Add volumes at the top level of a workflow. Each volume has a hub source, an absolute mount path outside the repository workspace, and a mode.

yaml
schema_version: v1
name: nightly-index

trigger:
  cron:
    schedule: "0 3 * * *"
    timezone: UTC

volumes:
  - name: dependency-cache
    source: hub://volumes/dependency-cache
    mount: /home/daytona/.elasticclaw/volumes/dependency-cache
    mode: rw
  - name: reference-data
    source: hub://volumes/reference-data:v1
    mount: /home/daytona/.elasticclaw/volumes/reference-data
    mode: ro

stages:
  - id: working
    entry: true
    on_enter:
      inject: |
        Use /home/daytona/.elasticclaw/volumes/reference-data for inputs.
        Store reusable generated files in /home/daytona/.elasticclaw/volumes/dependency-cache.

  - id: done
    terminal: true
    triggers:
      - message_contains: "[DONE]"

Fields

name - Workflow-local volume name. Use letters, numbers, hyphens, or underscores.

source - Hub volume ref in the form hub://volumes/<name> or hub://volumes/<name>:<tag>. Untagged refs use latest.

mount - Absolute path where the volume is extracted inside the sandbox. It must be outside the repository workspace.

mode - ro for read-only or rw for read/write. Defaults to ro.

Read-only and read/write leases

The hub leases every configured volume before the workflow agent runs. Read-only volumes can be attached by many workflow runs at the same time. Read/write volumes take an exclusive lease so only one active run can modify that volume ref.

When a read/write workflow finishes or is stopped by the hub, ElasticClaw asks the bridge to upload the mounted directory back to the hub. The hub stores a new artifact manifest and updates the volume ref.

RWX/shared-writer semantics are intentionally not supported. Use one read/write workflow run at a time for a given volume ref, or split data across separate volume names or tags.

Storage backend

Volumes use the same artifact_storage configuration as other hub-owned artifacts. Local storage is the default. Use S3-compatible storage when the hub should store volume data outside the hub filesystem.

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}

See Artifact Storage for local path and S3-compatible endpoint examples.

Mount path guidance

  • Mount volumes outside /home/daytona/.elasticclaw/workspaceand outside /workspace. Repository paths are blocked so volume files do not look like normal Git working tree files.
  • Use a stable path such as /home/daytona/.elasticclaw/volumes/<name>and mention it in the stage instructions or command configuration.
  • Do not store secrets in volumes. Use workspace secrets for sensitive values that should be injected as environment variables.

Operational notes

  • Volume data is transferred as compressed tar archives between the hub and the bridge. Large volumes add startup and shutdown time.
  • Back up both the hub database and artifact storage. The artifact store contains volume bytes; the database contains lease and workflow metadata.
  • If a workflow crashes before a read/write sync completes, the last successfully stored manifest remains the current volume ref.