Zexet Harness · Rust runtime
Zexet Harness docs
The short version: what it is, how to run it, and how your account fits in.
Quick start
Zexet is a composable agent harness with a Rust runtime (zexet-core, zexet-engine, zexet-host, zexet-desktop). The zexet launcher prefers the Rust build and falls back to the TypeScript harness for commands not yet ported.
$ npm install
$ npm run build:rs # cargo build --release --workspace
$ node bin/zexet.mjs version
$ node bin/zexet.mjs run --prompt "fix the login bug" --allow-write --strategy swarm
$ node bin/zexet.mjs serve --port 8752 --allow-write # Studio at http://127.0.0.1:8752/studio/Set a provider key first (for example ZEXET_API_KEY), or add providers later from the Studio settings.
Sign in a machine
zexet login connects a local install to your zexet.dev account with a device code, so no password ever touches the terminal. ships with the next CLI release
$ zexet login
Open https://zexet.dev/device and enter: BCDF-GHJK
Waiting for approval… ✓ Signed in as [email protected]Approve the request on zexet.dev/device. The CLI receives an API key (zx_live_…) scoped to your account; revoke it any time under Dashboard → API keys.
Commands
| Command | Purpose |
|---|---|
| zexet run "<goal>" --strategy … | Run a goal; auto picks a strategy heuristically |
| zexet team "<goal>" | Sequential specialist pipeline: explorer → research → edit → assets |
| zexet swarm [n] / debate [rounds] | Candidate swarm + judge, or adversarial debate + verdict |
| zexet plan / resume <checkpoint> | DAG planner + executor; resume skips completed tasks |
| zexet snapshot list|protect|restore | File snapshots taken before every agent write |
| zexet checkpoint list|restore <id> | Workspace time travel; every run captures a checkpoint |
| zexet serve / ui / desktop | Web Studio, TUI, native desktop app |
| zexet board / note / journal | Shared task board, notepad and the Documenter's journal |
Strategies
| Strategy | What happens |
|---|---|
| single | One guarded agent loop with tools |
| swarm | Several candidates attempt the goal; a judge picks or merges |
| debate | Agents argue positions over rounds; a verdict closes it |
| hierarchical | A planner builds a plan, specialists execute, state is checkpointed for resume |
Spill store & context
Long tool output is capped, not lost. The engine stores it once and hands the agent a spill://<id> marker; spill_read pages through the full text and spill_list recovers anything cut earlier in the run.
context_status reports where the current request's tokens go — system, tool schemas, conversation, tool output, harness context — against the usable window and the compaction line, plus prompt-cache reads and the active sandbox mode.
Sandbox modes
| Mode | Allows |
|---|---|
| read-only | No mutation at all. Plan and read runs are pinned here. |
| workspace-write | Writes confined to the workspace (plus explicitly consented roots). Default for cloud workspaces. |
| danger-full-access | Drops path confinement only. Destructive-shell and secret rules still apply. |
Set with --sandbox, ZEXET_SANDBOX or the sandbox config key. An unknown value aborts the boot instead of relaxing; escalation is operator-only.
Providers
Providers are pluggable behind one LLM interface with status-classified retries and failover. Switch provider or model mid-session from the Studio or with zexet provider. MCP servers, skills and platform connectors extend the tool set.
Cloud workspace
A cloud workspace is your own container running the native Rust engine (zexet-engine serve) and its Studio in workspace-write mode, with its own network, CPU, memory and process limits. Sessions keep running when you close the tab. GET /health on a workspace answers {"ok":true,"runtime":"rust"}.
- Create an account and confirm your email.
- Dashboard → Workspaces → New workspace.
- Press Open. You land in the Studio on a private address; the engine token never reaches your browser.
Self-hosted
Run the engine on your own server with Docker. Caddy in front provides HTTPS.
$ export ZEXET_UI_TOKEN=$(openssl rand -hex 24) # keep it: it is your login
$ export ZEXET_DOMAIN=agent.example.com # DNS A record → this server
$ docker compose -f deploy/cloud/docker-compose.yml up -d --build
# first visit, once: https://agent.example.com/studio/?token=$ZEXET_UI_TOKENThe engine refuses to listen beyond loopback without ZEXET_UI_TOKEN. After the first visit the browser holds an HttpOnly, SameSite=Strict cookie containing only a hash of the token.
API
Create keys under Dashboard → API keys or with zexet login. Keys start with zx_live_, are shown once, and are stored only as a SHA-256 hash.
$ curl -H "Authorization: Bearer zx_live_…" https://zexet.dev/api/v1/me
$ curl -H "Authorization: Bearer zx_live_…" https://zexet.dev/api/v1/workspaces| Scope | Grants |
|---|---|
| profile:read | GET /api/v1/me |
| workspaces:read | GET /api/v1/workspaces |
| workspaces:write | Reserved for workspace control from the CLI |
Security model
- The constitution blocks destructive shell patterns (unix + windows), writes outside the working directory and secret-file access.
- API keys are never returned to the browser after creation; provider keys are masked in the Studio.
- Your zexet.dev account supports two-factor authentication with recovery codes, session review and revocation.