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.

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 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.

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