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.

terminal
$ 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

terminal
$ 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

CommandPurpose
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|restoreFile snapshots taken before every agent write
zexet checkpoint list|restore <id>Workspace time travel; every run captures a checkpoint
zexet serve / ui / desktopWeb Studio, TUI, native desktop app
zexet board / note / journalShared task board, notepad and the Documenter's journal

Strategies

StrategyWhat happens
singleOne guarded agent loop with tools
swarmSeveral candidates attempt the goal; a judge picks or merges
debateAgents argue positions over rounds; a verdict closes it
hierarchicalA 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

ModeAllows
read-onlyNo mutation at all. Plan and read runs are pinned here.
workspace-writeWrites confined to the workspace (plus explicitly consented roots). Default for cloud workspaces.
danger-full-accessDrops 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"}.

  1. Create an account and confirm your email.
  2. Dashboard → Workspaces → New workspace.
  3. 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.

terminal
$ 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_TOKEN

The 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
$ curl -H "Authorization: Bearer zx_live_…" https://zexet.dev/api/v1/me
$ curl -H "Authorization: Bearer zx_live_…" https://zexet.dev/api/v1/workspaces
ScopeGrants
profile:readGET /api/v1/me
workspaces:readGET /api/v1/workspaces
workspaces:writeReserved 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.