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.

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.