Concepts
How ElasticClaw works — workflows, triggers, stages, scoped credentials, workspaces, and the lifecycle of an agent.
Architecture
ElasticClaw is a self-hosted workflow system for coding work. It connects issue tracker events to repeatable workflows that run agents, grant scoped credentials, open pull requests, and clean up. The core loop is:
- An issue enters a trigger status (e.g., Ready for Agent)
- The workflow selects stages and provisions a workspace from a workspace
- The agent receives the issue context and implements the fix
- The agent opens a PR and signals
[DONE] - ElasticClaw Server moves the issue to In Review and terminates the sandbox when the PR merges
Workflow Stages
A workflow connects a source of work to a governed agent workflow. Think of it as a rule plus lifecycle: when this happens, run this workflow with this access until this terminal state.
1. Trigger
A trigger event arrives from Linear, GitHub Issues, Shortcut, a webhook, a GitHub release, or another connected system. The workflow checks filters and decides whether to act.
2. Workspace
The workflow references a workspace that defines the sandbox environment: provider (Replicated, Daytona, etc.), bootstrap scripts, secrets, MCP servers, and the agent's initial instructions.
3. Sandbox
ElasticClaw Server provisions an isolated sandbox, injects the issue context as CONTEXT.md, and starts the agent. The agent has full terminal, git, and API access within its environment.
4. Signal & Wrap
When the agent sends [DONE], ElasticClaw Server validates the PR, moves the issue to the configured done_status, and marks the agent idle. The sandbox terminates when the PR merges or closes.
Agent Lifecycle
An agent moves through distinct states from creation to termination. Understanding these states helps debug why an agent is stuck or failed.
Waiting for a free slot (concurrency limit)
Sandbox being created by the provider
Bootstrap running, bridge connecting
Bridge registered, agent ready
Agent actively working
[DONE] sent, watching CI/reviews
Provisioning or bootstrap failed
Cleaned up, sandbox destroyed
How a Workflow Decides
When a webhook arrives, the workflow evaluates multiple filters in sequence. All must pass for an agent to spawn.
Each filter is a gate. The first failure stops evaluation — no agent is created, and the event is logged as not_actionable.
Key Terms
ElasticClaw Server
The central server that receives webhooks, evaluates workflows, manages credentials and execution providers, serves the web UI, and routes agent traffic. Configured via hub.yaml.
Agent
A single running agent instance. Each agent is backed by one sandbox and has a unique ID, status, and lifecycle.
Workflow
A configured workstream that listens for issue events, applies trigger filters, selects a workspace, grants scoped access, and runs the agent through workflow stages.
Workspace
A reusable definition of a sandbox environment: bootstrap scripts, files, secrets, model config, and provider settings.
Stages
A state machine attached to a workflow that defines actions at each stage: creation, implementation, done, review, CI, merge, failure, and cleanup.
Sandbox
The isolated compute environment that hosts an agent. Can be a VM (Replicated, Daytona), container, or serverless function depending on the provider.