Skip to main content
First time spawning an agent? Start with the first agent quickstart — it walks you through one end-to-end. The page below is the reference.

​
The basic call

fracta spawn <task-name> --runtime claude --contract "Hunt for SSO anomalies in the last 24h."
This creates an agent named <task-name>, picks the claude runtime, hands it the contract as its initial prompt, and supervises the resulting subprocess (or pod, depending on deployment mode) until it exits.

​
Inputs that shape the agent

InputWhat it does
Task nameIdentifies the agent in fracta list, names its workspace (worktree branch or directory), and is how you address it via fracta say, fracta peek, fracta merge, fracta kill.
RuntimeWhich AI CLI runs as the agent process — claude, codex, opencode. The runtime adapter handles invocation, session continuation, and output capture.
ContractThe agent’s initial instruction — the what and why of its work. Stored alongside the agent’s state so resumes and fracta say follow-ups have the original framing.
CredentialsThe control plane materializes a credential profile (LLM keys, MCP backend secrets) into the agent’s environment before launch. See the credential pipeline guide.

​
What the control plane does on spawn

  1. Admission check. Concurrency limits, queue eligibility. If full, the agent enters the queue.
  2. Workspace creation. Either a git worktree (local-process) or a per-agent directory (Docker Compose / Kubernetes). See Workspaces.
  3. Credential materialization. Profile-driven secrets are written into the agent’s environment.
  4. Process launch. The runtime CLI is started as a subprocess (local-process / Docker Compose) or as a Kubernetes Job (k8s mode).
  5. Wiring. The agent’s MCP client points at the gateway. Its mailbox is initialized. Its intent is set to a default.
  6. State write. The agent appears in fracta list with status running.

​
Lifecycle states

The orchestrator tracks each agent through a small state machine:
StateMeaning
queuedAdmission control held it; will start when capacity frees up
runningProcess is alive and the agent is doing work
completedProcess exited cleanly; final output captured
failedProcess exited non-zero or crashed
stoppedKilled via fracta kill (or reaped after timeout)
State transitions are persisted in the state store (SQLite or PostgreSQL). They survive restarts of the control plane.

​
Talking to an agent after it’s running

CommandWhat it does
fracta listSee every agent — status, intent, last update, unread message count
fracta peekRead an agent’s recent semantic output without disturbing it
fracta watchStream an agent’s events live over SSE
fracta saySend a follow-up; the agent resumes its session with the new message
fracta merge(Local-process only) Merge the agent’s feature branch into the current branch — agent stays alive
fracta killTear it down: workspace removed, branch deleted, state cleaned up
fracta merge is non-destructive — the agent keeps running and can iterate further. fracta kill is the terminal operation.

​
Spawning many at once

The swarm pattern is many agents in parallel. fracta spawn is happy to be invoked repeatedly: 
fracta spawn refactor-auth     --runtime claude --contract "Refactor src/auth.go ..."
fracta spawn refactor-tokens   --runtime claude --contract "Refactor src/tokens.go ..."
fracta spawn upgrade-deps      --runtime codex  --contract "Bump deps in go.mod ..."
Each gets its own workspace; admission control enforces the configured concurrency limit. Use fracta list to watch all of them at once.

​
Source