You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: concepts.mdx
+84-37Lines changed: 84 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,67 +5,114 @@ description: "Core terminology and mental model for UseZombie."
5
5
6
6
## Core terminology
7
7
8
-
These are the building blocks of UseZombie. Understanding them will help you navigate the docs, configure workspaces, and interpret run results.
9
-
10
8
<AccordionGroup>
11
-
<Accordiontitle="Spec">
12
-
A markdown file describing what you want built. Specs are format-agnostic — structured sections, free-form prose, or bullet lists all work. The agent reads natural language and infers implementation intent from your codebase. A spec is the input to every run.
9
+
<Accordiontitle="Zombie">
10
+
A persistent, always-on agent process. A zombie has a config (YAML + markdown), a trigger
11
+
(how it receives events), a set of skills (what tools it can use), and a set of credentials
12
+
(secrets it needs — but never sees). Once started, a zombie runs continuously, restarts on
13
+
crash, and waits for events on its inbox queue.
13
14
</Accordion>
14
15
15
-
<Accordiontitle="Run">
16
-
A single execution of a spec. Each run has a lifecycle state: `QUEUED`, `RUNNING`, `COMPLETED`, or `FAILED`. A completed run produces artifacts (the implementation diff, gate logs) and a scorecard. Runs are immutable once finished — to retry, create a new run.
16
+
<Accordiontitle="ZombieConfig">
17
+
The YAML + markdown file that defines a zombie. YAML frontmatter carries machine-readable
18
+
config (trigger, skills, credentials, budget); the markdown body carries agent instructions
19
+
in natural language. The CLI compiles this to JSON before uploading — the server only ever
The sequential validation cycle that runs after the agent finishes implementing: `make lint`, then `make test`, then `make build`. If any gate fails, the agent reads the error output, self-repairs, and re-runs the full gate sequence. The loop runs up to 3 times by default. This is what makes UseZombie runs self-repairing.
41
+
<Accordiontitle="Trigger">
42
+
How a zombie receives events. Currently supported: `webhook`. The `source` field is a
43
+
human-readable label (e.g. "email", "github", "slack") — it appears in logs but is not used
44
+
for routing. Routing uses the zombie's unique ID. The `token` field is the Bearer token
45
+
callers must include.
21
46
</Accordion>
22
47
23
-
<Accordiontitle="Scorecard">
24
-
Quality metrics attached to every completed run. Four weighted dimensions:
25
-
26
-
-**Completion** (40%) — Did the agent implement everything the spec asked for?
27
-
-**Error rate** (30%) — How many gate failures occurred before passing?
28
-
-**Latency** (20%) — Wall-clock time from enqueue to PR.
29
-
-**Resource efficiency** (10%) — Token and compute usage relative to task complexity.
A named capability available to a zombie's agent. Skills are declared in the config and
50
+
resolved by the runtime — the agent calls a skill by name, the runtime injects the
51
+
credential and executes the API call outside the sandbox. Examples: `agentmail`, `github`,
52
+
`slack`. Skills are the only way agents interact with external services.
32
53
</Accordion>
33
54
34
-
<Accordiontitle="Workspace">
35
-
A bound GitHub repository with associated entitlements, billing configuration, and agent settings. When you run `zombiectl workspace add`, you create a workspace. All runs, harnesses, and billing are scoped to a workspace.
55
+
<Accordiontitle="Credential firewall">
56
+
The security boundary between your secrets and the agent. Credentials are stored encrypted
57
+
in the UseZombie vault. When an agent invokes a skill, the firewall retrieves the secret,
58
+
makes the outbound API call, and returns only the response. The agent process never receives
59
+
the raw credential — not as an environment variable, not as a function argument, not in any
60
+
log. If the agent is compromised, your keys are not.
36
61
</Accordion>
37
62
38
-
<Accordiontitle="Harness">
39
-
Workspace-scoped agent configuration. A harness defines how agents operate within a workspace: which source repositories to read, which compiler/runtime versions to use, and which agent profiles are available. Operators store source references, compile version constraints, and activate profiles through the harness.
63
+
<Accordiontitle="Activity stream">
64
+
An append-only audit log of every action a zombie takes. Every event received, every skill
65
+
invoked, every response returned — timestamped and queryable. `zombiectl logs` streams the
66
+
activity log in real time. The stream is stored in Postgres and paginated by cursor for
67
+
replay and debugging.
40
68
</Accordion>
41
69
42
-
<Accordiontitle="Agent profile">
43
-
A named configuration within a harness that defines the model, repair strategy, and gate settings for runs. Each profile accumulates its own score history across runs, making it easy to compare configurations. Switch profiles to experiment with different agent behaviors without changing workspace settings.
70
+
<Accordiontitle="Session checkpoint">
71
+
The persisted state between event deliveries. After each event is processed, the zombie's
72
+
agent state (conversation history, working memory) is checkpointed to Postgres. If the
73
+
process crashes, the next event picks up from the last checkpoint. This is what makes
74
+
zombies stateful across runs — they remember context across events.
44
75
</Accordion>
45
76
46
-
<Accordiontitle="Worktree">
47
-
An isolated git working directory created for each run. The agent implements the spec in a worktree branched from the workspace's default branch, ensuring no changes touch main until you approve the PR. Worktrees are cleaned up automatically after run completion.
77
+
<Accordiontitle="Kill switch">
78
+
Stop a zombie immediately from `zombiectl kill` or the web UI. The running agent process is
79
+
terminated mid-action — no new events are processed, no further billing. The zombie's state
80
+
is preserved so it can be restarted cleanly. Use the kill switch when an agent is misbehaving
81
+
or consuming unexpected resources.
48
82
</Accordion>
49
83
50
-
<Accordiontitle="NullClaw">
51
-
The embedded agent runtime that executes specs inside the sandbox. NullClaw receives the spec, injected codebase context, and tool access, then produces an implementation. It operates within the worktree and has no access outside the sandbox boundary.
84
+
<Accordiontitle="Budget">
85
+
Per-event spending limits. `max_tokens_per_event` caps the LLM token budget per event
86
+
delivery. `max_wall_seconds` caps wall-clock time. If either limit is hit, the event is
87
+
terminated and a budget breach is logged to the activity stream. One bad prompt never
88
+
becomes an infinite burn.
52
89
</Accordion>
53
90
54
-
<Accordiontitle="Executor">
55
-
The sidecar process (`zombied-executor`) that owns the sandbox lifecycle. The executor spawns NullClaw agents, manages worktree creation and cleanup, enforces resource limits (CPU, memory, time), and reports execution results back to the worker.
91
+
<Accordiontitle="Workspace">
92
+
A container for zombies, billing, and access control. All zombies, credentials, and billing
93
+
are scoped to a workspace. Multiple team members can share a workspace with role-based
94
+
access.
56
95
</Accordion>
57
96
58
-
<Accordiontitle="Context injection">
59
-
The process of providing relevant codebase context — file contents, module structure, dependency graphs — to agents alongside the spec. Good context injection is what separates accurate implementations from hallucinated ones. This is a key area of ongoing improvement in UseZombie.
97
+
<Accordiontitle="NullClaw">
98
+
The embedded agent runtime that executes inside the sandbox. NullClaw receives the zombie's
99
+
instructions, injected skill definitions, and events, then produces responses and skill
100
+
invocations. It operates inside an isolated sandbox process and has no direct access to
101
+
credentials or external networks — everything flows through the firewall.
60
102
</Accordion>
61
103
62
-
<Accordiontitle="Agent relay">
63
-
A stateless communication model where `zombied` acts as a pass-through between `zombiectl` and the workspace's LLM provider. The CLI sends tool definitions (read_file, list_dir, glob) with each request. The model decides which files to read via tool calls. The CLI executes tools locally on the developer's laptop and sends results back. Files never leave the machine unless the model explicitly asks for them.
64
-
65
-
Used by `spec init` and `run --preview` for lightweight, interactive agent sessions. The pipeline model (sandbox + worker) is used for full `run` execution.
104
+
<Accordiontitle="Executor">
105
+
The sidecar process (`zombied-executor`) that owns the sandbox lifecycle. The executor
memory, time), and reports execution results back to the event loop. The executor is also
108
+
used for harness compilation and spec preview in legacy v1 workflows.
66
109
</Accordion>
67
110
68
-
<Accordiontitle="Steering">
69
-
An agent-to-agent workflow where an external coding agent (Claude Code, Codex, OpenCode) submits specs to UseZombie. The external agent handles planning and spec authoring; UseZombie handles execution with verified gates. This lets you compose agent capabilities: one agent thinks, another builds with guardrails.
111
+
<Accordiontitle="Event loop">
112
+
The persistent process that drives a zombie. The event loop claims a zombie from the
113
+
dispatch queue, loads its config and session checkpoint, waits for events on its Redis
114
+
Streams inbox, delivers each event to NullClaw, checkpoints state after processing, and
115
+
acknowledges the Redis message (at-least-once delivery). Events are processed sequentially
Copy file name to clipboardExpand all lines: how-it-works.mdx
+21-17Lines changed: 21 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,12 +21,12 @@ Your agent never sees raw credentials. It makes requests. The firewall intercept
21
21
## Step by step
22
22
23
23
<Steps>
24
-
<Steptitle="Connect your agent">
25
-
Push your agent code to a workspace. UseZombie wraps it in a sandboxed process with resource limits (CPU, memory, wall time). The agent starts running immediately and restarts automatically on crash.
24
+
<Steptitle="Install a zombie">
25
+
Run `zombiectl install <template>` to create a zombie config file. Edit it to set your trigger, skills, and agent instructions. Run `zombiectl up` to deploy. UseZombie provisions a webhook endpoint, starts the event loop, and your agent is live in seconds.
26
26
</Step>
27
27
28
28
<Steptitle="Store credentials — once">
29
-
Add API keys, tokens, and secrets to the workspace credential store via `zombiectl skill-secret put` or Mission Control. Credentials are encrypted at rest and never passed into the sandbox.
29
+
Add API keysand tokens via `zombiectl credential add` or Mission Control. Credentials are encrypted at rest and never passed into the sandbox. Your agent invokes a skill by name; the firewall handles the rest.
@@ -38,7 +38,7 @@ Your agent never sees raw credentials. It makes requests. The firewall intercept
38
38
</Step>
39
39
40
40
<Steptitle="Webhooks arrive without ngrok">
41
-
Register webhook sources (GitHub, Slack, email, custom HTTP) on the workspace. UseZombie provides a stable inbound endpoint and routes matching events to your agent process. No tunneling, no port forwarding, no custom servers.
41
+
Every zombie gets a stable, unique webhook URL at `https://hooks.usezombie.com/v1/webhooks/{zombie_id}`. Point GitHub, Slack, email, or any HTTP source at it. Events are authenticated with a Bearer token and queued to the zombie's inbox. No tunneling, no port forwarding, no custom servers.
42
42
</Step>
43
43
44
44
<Steptitle="Observe and control">
@@ -72,27 +72,31 @@ The agent makes a plain HTTP request. The firewall resolves the right credential
72
72
sequenceDiagram
73
73
participant CLI as zombiectl
74
74
participant API as zombied API
75
+
participant WH as Webhook endpoint
75
76
participant Q as Redis Streams
76
-
participant W as zombied worker
77
-
participant S as Sandbox process
77
+
participant EL as Event loop (worker)
78
+
participant S as NullClaw sandbox
78
79
participant F as Credential firewall
79
80
80
-
CLI->>API: POST /v1/agents (agent config)
81
-
API->>Q: enqueue agent_start
82
-
Q->>W: claim work
83
-
W->>S: spawn sandboxed process
84
-
S->>F: outbound requests (no credentials)
81
+
CLI->>API: POST /v1/webhooks/install (zombie config)
82
+
WH->>API: POST /v1/webhooks/{zombie_id} (inbound event)
Copy file name to clipboardExpand all lines: index.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,10 +17,10 @@ So we killed the old approach and pivoted. UseZombie is now a runtime for always
17
17
18
18
## What UseZombie does
19
19
20
-
UseZombie is agent hosting infrastructure. Connect your agents, and we handle credentials, webhooks, and walls — your agents run 24/7 without ever seeing your keys.
20
+
UseZombie is agent hosting infrastructure. You bring your agent; we handle credentials (hidden from the sandbox), webhooks (wired automatically), audit logs (every action timestamped), and a kill switch. Your agent runs 24/7 without ever seeing a password.
0 commit comments