Workspaces

Workspaces define the runtime environment, files, repository access, and environment variables used by workflows.

Create a workspace

A workspace is the runtime environment for workflow-created agents. It starts with an elasticclaw-config.yamlfile plus instruction files such as AGENTS.md and TOOLS.md. Create one locally, edit the generated files, then push it to ElasticClaw Server.

bash

elasticclaw workspace create --name my-app
cd .elasticclaw/workspaces/my-app

elasticclaw-config.yaml

yaml

schema_version: v1
name: my-app

repositories:
  - repo: my-org/my-app
    permissions: write

env:
  NODE_ENV: development
  GITHUB_TOKEN:
    secret: github_app

provider: replicated

Workspace fields

schema_version — Optional schema marker; defaults to v1.

name — Workspace identifier.

repositories — GitHub repositories the workspace can access, with read or write permissions. Supports glob patterns such as owner/* or *-infra-* when a GitHub App is configured.

env — Inline environment values or { secret: name } references resolved from workspace or server secrets.

provider — Optional sandbox provider override for agents created from this workspace.

llm_key and default_model — Optional model key and model override.

nix and docker — Optional runtime setup flags.

tags and color — Optional dashboard metadata for agents created from this workspace.

Workspace v2 schema

schema_version: 2 is a strict, typed replacement for the v1 workspace format. It separates authority (repositories, credentials, source-control and CI connections) from workflow behavior, and it references secrets by name instead of embedding values.

yaml

schema_version: 2
name: engineering

repositories:
  primary:
    provider: github
    repository: elasticclaw/elasticclaw
    permissions: write
    source_control: github-production

execution:
  provider: daytona
  nix: true
  docker: true
  tools:
    - git
    - gh

credentials:
  github_app:
    secret: GITHUB_APP_PRIVATE_KEY
  depot_token:
    secret: DEPOT_TOKEN
  linear_api_key:
    secret: LINEAR_API_KEY

source_control:
  connections:
    github-production:
      provider: github
      credentials: github_app

ci:
  connections:
    github-actions:
      provider: github_actions
      source_control: github-production
      credentials: github_app
      capability_restrictions:
        trigger_run: false
        cancel_run: false
    depot:
      provider: depot
      credentials: depot_token
  pipelines:
    github-pr:
      connection: github-actions
      repository: primary
      workflow: ci.yml
    depot-container:
      connection: depot
      repository: primary
      project: elasticclaw
      pipeline: container-build

issue_trackers:
  connections:
    product-linear:
      provider: linear
      credentials: linear_api_key

review_systems:
  connections:
    github-reviews:
      provider: github
      source_control: github-production

knowledge:
  sources:
    engineering-principles:
      type: workspace_files
      scope: organization
      required: true
      paths: [ENGINEERING.md, PRODUCT.md]
    repository-instructions:
      type: repository_files
      scope: repository
      required: true
      paths: [AGENTS.md]

Referencing secrets

v2 workspaces never embed secret values. Create the secret on the server, then reference it by name in the workspace YAML.

bash

elasticclaw secret create GITHUB_APP_PRIVATE_KEY --workspace engineering   --value "$GITHUB_APP_PRIVATE_KEY"

# Reference the secret inside elasticclaw-config.yaml
credentials:
  github_app:
    secret: GITHUB_APP_PRIVATE_KEY

The credentials.*.secret value is only the secret name. The server resolves the actual value when the workspace is assembled. Multi-line PEM blocks, token strings, or any other secret material in the YAML are rejected by validation.

Workspace v2 fields

schema_version — Use 2 or v2. Unknown top-level keys are rejected.

repositories — Named map of repositories. Each entry sets provider, repository (owner/repo), permissions (read or write), optional source_control connection, and optional checkout (ref, depth).

execution — Sandbox provider and capability restrictions. provider names the provider; nix/docker enable runtime setup; tools lists required tooling. Use capability_restrictions to narrow provider capabilities, for example disabling execute_command or dependency_update.

credentials — Named map of secret references. Each value uses secret: NAME where NAME is a secret stored on the server. Never paste the secret value into the YAML.

source_control — Named source-control connections (for example github) linked to credentials.

ci — CI connections (GitHub Actions, Depot, Jenkins) and named pipelines that reference those connections and workspace repositories.

issue_trackers and review_systems — Named connections for issue trackers (for example linear) and review systems (for example github, greptile).

knowledge — Sources used for context bundles: workspace_files, repository_files, or retrieval. Paths must be relative and must not contain ...

Repository names, connection names, and credential names must match ^[A-Za-z0-9][A-Za-z0-9_.-]*$. Set permissions: write on repositories that will receive branches or pull requests from effects such as dependency.update.

Push a workspace

Pushing a workspace publishes elasticclaw-config.yaml and workspace files. Push workflow YAML separately into the workspace.

bash

elasticclaw workspace create --name my-app
elasticclaw workspace push my-app
elasticclaw workspace push my-app --path ./custom/my-app
elasticclaw workflow push --workspace my-app .elasticclaw/workflows
elasticclaw workspace list
elasticclaw workspace show my-app
elasticclaw workspace rm my-app

Workspace scripts

Workspace scripts are copied into each agent workspace under scripts/. Use them for deterministic workflow steps such as tests, scanners, deploy-preview checks, or build gates.

text

.elasticclaw/workspaces/my-app/
|-- elasticclaw-config.yaml
|-- AGENTS.md
|-- TOOLS.md
`-- scripts/
    |-- validate.py
    `-- checks/
        `-- security.py

python

# scripts/validate.py
import json

print("running validation...")
print(json.dumps({
    "status": "clean",
    "reason": "No issues found",
}))

yaml

stages:
  - id: validation
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      run:
        command: python3 scripts/validate.py
        output: validation
    gate:
      output: validation
      pass:
        path: status
        values: [clean]

elasticclaw workspace push includes files under scripts/ recursively. Hidden script files and hidden script directories are skipped.

Workspace flake devShell

When a workspace includes flake.nix, deterministic workflow run commands and dependency updates execute inside the workspace devShell. This ensures declared tools are available without the agent having to install them manually.

text

.elasticclaw/workspaces/my-app/
|-- flake.nix
|-- flake.lock
|-- elasticclaw-config.yaml
|-- AGENTS.md
`-- scripts/
    `-- validate.py

Push flake.nix and flake.lock with the workspace. The server stages both files after syncing the workspace so the flake is available for run actions.

Workflows belong to exactly one workspace on ElasticClaw Server. Put shared runtime policy in the workspace and event-specific behavior in each workflow file.