Autonomous operating system for self-custodial onchain operations.
ZERO is an open-source runtime and operator terminal for running autonomous capital operations without giving up custody. It starts with onchain perpetual markets: paper-first execution, safety gates, local journals, Hyperliquid read-only/live boundaries, self-evolution loops, public proof packets, and intelligence contracts.
Not another trading bot. ZERO is the control plane that makes autonomous onchain operations inspectable, interruptible, and self-custodial.
The first proof is intentionally simple: the runtime boots in paper mode, live
risk refuses closed, public proof packets verify, and no custody is required.
The live proof bridge is separate: a redacted zero.live_trading_evidence.v1
packet proves operator-owned Hyperliquid live execution evidence exists without
publishing raw venue records, wallet addresses, or private journals.
Run the same checks locally with:
just paper-api-smoke
just public-proofZERO's public Railway template is live: Dockerfile build, railway.toml,
/health, durable /data journal volume, Railway doctor, redacted deployment
evidence packs, and paper-mode live-risk refusal.
Live public paper demo: https://zero-production-5214.up.railway.app
Railway template: https://railway.com/deploy/zero-paper-runtime
Use docs/railway-template.md as the marketplace configuration source of truth. The current Railway Template Publish Packet is tracked in contracts/distribution/railway-template.json. The Railway partner submission packet is tracked in docs/railway-partner.md.
scripts/railway_doctor.py https://zero-production-5214.up.railway.appZERO has three non-negotiable product rules:
- The engine is open source and useful without a hosted ZERO control plane.
- Operators keep custody; live-capital paths are local, explicit, and gated.
- Public reputation is built from redacted proof, not screenshots or claims.
ZERO's first-run path is local, paper-first, and does not need exchange credentials:
git clone https://github.com/zero-intel/zero.git
cd zero
just bootstrap
just paper-apiIn another terminal:
cd zero/cli
cargo run -q -p zero-os -- --api http://127.0.0.1:8765Inside the terminal, press Ctrl+5 or run /cockpit-mode for the live
cockpit. In paper/default mode it should refuse live risk and show the reason:
live cockpit
live_mode=refused ready=false risk_allowed=false controls_ready=false
next: fix preflight check live_executor: live executor not configured
operator: handle=local-operator role=owner scope=local-private
preflight: passed=2/10 failed=8
immune: open=2 risk_blocking=2
reconciliation: not_configured risk_allowed=false
receipts: total=0 accepted=0 refused=0 exchange_error=0
actions: reduce=/pause-entries /kill /flatten-all resume=/resume-entries
That refusal is the product boundary working: the public runtime can be inspected, rehearsed, and extended without pretending to be a hosted custody service or an unattended live-capital promise.
This repository is the public product page and open-core engineering home for ZERO. It is launch-ready for paper runtime work, operator-terminal development, safety-gate design, public proof contracts, self-evolution workflows, ZERO Network contracts, and ZERO Intelligence API contracts.
For live capital, the public stance is exact: ZERO is a self-custodial local runtime, not a hosted custody service. Operators bring their own wallet, exchange account, limits, journals, kill switch, and disclosure policy. The runtime can only increase risk after local custody, reconciliation, immune, journal, dead-man, and operator-friction checks pass.
| Question | Public answer |
|---|---|
| Can a new engineer run ZERO today? | Yes: clone, bootstrap, run the paper API, inspect it through the CLI, and verify proof packs. |
| Can ZERO trade live? | Operator-owned deployments have live Hyperliquid execution evidence represented by zero.live_trading_evidence.v1. |
| Does the public repo publish raw live records? | No. It publishes redacted evidence, hash-only proof, canary workflows, and verifiers. |
| Does ZERO custody funds? | No. Live mode is local, self-custodial, explicit, and gated. |
| Is unattended live trading the default? | No. Paper is default; live risk requires canary review and local operator responsibility. |
Onchain markets are open 24/7. Leverage punishes attention failure. The old stack asks operators to stitch together dashboards, alerts, exchange tabs, copy-trading feeds, scripts, and private spreadsheets, then somehow stay disciplined under stress.
ZERO turns that workflow into an explicit operating system:
- A runtime that evaluates, rejects, executes, and records decisions.
- A terminal that keeps the operator in control.
- A safety model that makes risk-reducing actions fast and risk-increasing actions deliberate.
- A public proof surface for profiles, leaderboards, and verification.
- A free growth-mode intelligence layer built from verified autonomous behavior.
The default mode is paper. Live operation is self-custodial, explicit, and guarded by preflight checks.
| Surface | Role | Public status |
|---|---|---|
| ZERO Runtime | Python engine for paper execution, production-parity OODA reports, live-readiness contracts, journals, safety gates, strategy adapters, venue adapter interfaces, local evolution gates, and canary evidence. | Open source |
| ZERO Terminal | Rust CLI/TUI for setup, diagnostics, state inspection, replay, live cockpit views, and supervised actions. | Open source |
| ZERO Evolution | Local memory, genesis proposals, research reports, decision-stack review, guardian review, red-team, paper canaries, calibration, promotion plans, local apply receipts, rollback receipts, and evolve loops that let ZERO improve under review. | Memory, genesis, research, decision stack, paper-first evolve gates, local apply, and rollback execution open; protected promotion remains human-reviewed |
| ZERO Network | Public-safe profiles, empty/active/stale page states, leaderboards, verification badges, profile verification, and deterministic proof-chain packets. | Open source contracts |
| ZERO Intelligence | Delayed public snapshots plus growth-mode free realtime APIs, history, cohorts, webhooks, exports, and future SLAs built from verified autonomous behavior. | Open contracts + free operator-growth access |
| Capability | Public repo state |
|---|---|
| Paper engine | Runnable now with deterministic fixtures, local API, CLI, Docker, and Railway paths. |
| Live market data | Runnable now through read-only Hyperliquid public info calls when enabled. |
| Live readiness | Runnable now as local preflight, cockpit, certification, reconciliation, immune, receipt, evidence, and canary-policy contracts. |
| Live execution | Private operator deployments have live Hyperliquid execution evidence represented by the redacted public packet. New live capital remains operator-owned, self-custodial, and gated by local custody, preflight, journal, kill-switch, reconciliation, and canary policy. |
| Self-evolution | Local memory, genesis proposal core, research command chain, decision-stack lenses/layers/modifiers, production-parity OODA reporting, and paper-first evolve gates exist now with redacted extraction, append-only journals, guardian classification, hunt/edge/convergence/thesis/score/meta/sharpen reports, public evaluation surfaces, live-shadow fail-closed parity, red-team review, sandbox candidate mutation, paper canary, calibration, promotion plan, rollback plan, promotion verification, explicit local apply, rollback receipts, API readouts, and expanded read-only MCP snapshots for runtime status, parity, health, journal, rejection audit, memory stats, immune state, backtest summary, evidence bundle, and safety catalog. Protected live-code evolution remains human-reviewed. |
| Public proof | Runnable now through deterministic demo proof packs, redacted Network contracts, deterministic Network proof packs, zero.live_trading_evidence.v1, canary bundles, exchange-evidence normalization, recursive checksums, and operator report verification. |
| Intelligence API | Contracted now as ZERO Intelligence; growth-mode realtime access is free to increase operator density. Future commercial work is higher scale, retention, redistribution, managed persistence, warehouse history, and SLAs. |
flowchart LR
A["Market data and strategy inputs"] --> B["ZERO Runtime"]
B --> C["Safety gates and risk policy"]
C --> D["Paper or self-custodial live execution"]
B --> E["ZERO Terminal"]
B --> F["Audit journal"]
F --> G["ZERO Network proof"]
G --> H["ZERO Intelligence"]
- Run the local paper engine against bundled example candles.
- Run a bounded paper OODA runtime cycle with durable cycle records.
- Run a production-parity OODA report that mirrors paper intents through a
disabled live executor, proves fail-closed behavior, and emits
zero.runtime.production_parity.v1. - Extract local public-safe memory from paper decisions and generate
knowledge.md. - Classify fixture-backed genesis proposals as accepted, rejected, or escalated without applying code changes.
- Run the paper-first evolve harness for accepted genesis proposals; the default run path materializes a sandbox candidate tree, promotion plan, rollback plan, and promotion verification without mutating the checkout or pushing a branch.
- Explicitly apply and roll back allowed docs/example evolve candidates in a local checkout with exact approval phrases, original/candidate hash checks, apply receipts, and rollback receipts.
- Run the paper-only research command chain for hunt, edge, convergence, thesis, score, meta, and sharpen reports from public fixtures.
- Inspect the public decision stack for lenses, layers, modifiers, and paper/live separation.
- Add a declarative paper strategy runner with conformance output.
- Start a local paper API and inspect operator state.
- Use the Rust CLI for health checks, status, replay, and supervised actions.
- Query Hyperliquid read-only market data without exposing funds.
- Exercise live-readiness, immune, reconciliation, and certification contracts without placing capital at risk.
- Keep the full-screen terminal cockpit open with Ctrl+5 or
/cockpit-modewhile the read-only/live/cockpitpacket is polled from the engine. - Inspect public-safe local live execution receipts from the operator CLI, including accepted/refused/exchange-error counts and hash-only receipt proof.
- Capture signed, public-safe live evidence packets for supervised canary rehearsal without leaking credentials or raw private journals.
- Inspect the live canary policy lifecycle for readiness, arm/disarm, launch
window, evidence, shadow review, qualification, follow-through, and next
action through
/live/canary-policyor the operator CLI. - Run the maintained live canary rehearsal collector in fail-closed public paper mode, or in explicit operator-owned canary mode when local live gates are ready.
- Verify canary evidence bundles locally before sharing them as launch or incident evidence.
- Verify the committed redacted live trading evidence packet that summarizes private operator Hyperliquid fills, trades, and live decisions without raw custody material.
- Attach public-safe exchange-side order/fill evidence to canary bundles and verify it against ZERO live receipts without exposing raw venue payloads.
- Run and verify a one-command live canary operator workflow that collects, attaches, verifies, checksums, and reports public-safe evidence.
- Capture a read-only live cockpit drill bundle for preflight, immune, reconciliation, certification, receipt, evidence, metrics, and audit packets.
- Package release assets with checksums.
- Deploy the paper runtime on Railway or Docker.
- Generate public-safe Network index, profile pages, leaderboard pages, and Intelligence contract artifacts.
The self-evolving loop that makes ZERO a complete autonomous operating system is now implemented as a public-safe control plane: local memory, genesis proposal classification, paper-only research, public decision-stack review, production-parity OODA reports, sandbox candidate mutation, promotion/rollback evidence, explicit local apply, rollback receipts, and paper-first evolve gates exist. Protected live-code evolution remains human-reviewed. See Memory Core, Genesis, Research Command Chain, Decision Stack, Evolve Harness, and Private Engine Capability Gap Audit.
ZERO should earn trust through behavior that another engineer can verify:
- Run paper mode locally or on Railway.
- Run
just public-proofto verify the demo proof pack, Network proof chain, redacted live trading evidence, read-only MCP server, and committed MCP transcript together. - Verify
docs/proof/network/network-proof-pack.jsonagainst its profile, leaderboard, deployment identity, and ingestion artifacts. - Generate a signed journal root from local JSONL streams with
zero-journal-root, attach anchor metadata withzero-journal-anchor, and export a redacted proof pack withzero-journal-proof. - Inspect runtime, risk, live cockpit, immune, account, and reconciliation packets through the CLI/API.
- Rehearse a live canary in fail-closed mode.
- Attach public-safe exchange-side evidence when an operator-owned live canary is ready.
- Verify the bundle, recursive checksums, privacy flags, live canary policy, and report with local scripts before publishing anything.
That flow is implemented for refusal-mode rehearsal and redacted live-evidence verification today. Raw accepted live canary records require an operator-owned Hyperliquid wallet and explicit local disclosure; they are not part of public CI.
This is a shortened excerpt from scripts/demo_capture.sh, the maintained
local paper-mode demo. It demonstrates the terminal flow without launching the
interactive TUI:
$ zero --api http://127.0.0.1:8765 doctor
[ ok] engine_reachable zero-paper-engine v0.1.2
[ warn] auth no token set — read-only endpoints only
[ warn] live_preflight not ready: live_executor, wallet, key, journal
$ zero --api http://127.0.0.1:8765 run status
engine: regime=PAPER MARKET. Local deterministic demo.
equity=$10000.00 open=0 recovery=ephemeral
$ zero --api http://127.0.0.1:8765 run risk
risk: OK equity=$10000.00 peak=$10000.00 dd=0.00% open=0
$ curl -fsS -H 'content-type: application/json' -d '{...}' /execute
{"accepted": true, "coin": "BTC", "side": "buy", "simulated": true}
$ curl -fsS http://127.0.0.1:8765/network/profile
{"schema_version": "zero.network.profile.v1", "mode": "paper", "verification": {"status": "verified"}}
$ curl -fsS http://127.0.0.1:8765/deployment/heartbeat
{"schema_version": "zero.deployment.heartbeat.v1", "liveness": {"status": "paper_only"}}
$ curl -fsS http://127.0.0.1:8765/intelligence/snapshot
{"schema_version": "zero.intelligence.snapshot.v1", "access": {"class": "public_delayed", "delay_s": 900}}
$ curl -fsS http://127.0.0.1:8765/live/preflight
{"schema_version": "zero.live_preflight.v1", "live_mode": "refused", "ready": false}
$ zero --api http://127.0.0.1:8765 run live-cockpit
live-cockpit: live_mode=refused ready=false risk_allowed=false
$ zero --api http://127.0.0.1:8765 run live-receipts
live-receipts: status=empty total=0 accepted=0 refused=0 exchange_error=0
$ zero --api http://127.0.0.1:8765 run live-canary
live-canary: ready=false armed=false qualified=false publishable=false accepted_live=false
$ zero --api http://127.0.0.1:8765 run runtime-parity
runtime-parity: ok=true production_ooda=true paper_only=true live_trading_claimed=false
$ curl -fsS http://127.0.0.1:8765/operator/context
{"schema_version": "zero.operator_context.v1", "handle": "local-operator", "scope": "local-private"}
$ curl -fsS http://127.0.0.1:8765/memory
{"schema_version": "zero.memory.snapshot.v1", "stats": {"active_entries": 0}}
$ curl -fsS http://127.0.0.1:8765/genesis
{"schema_version": "zero.genesis.snapshot.v1", "mode": "plan-only"}
$ curl -fsS http://127.0.0.1:8765/evolve
{"schema_version": "zero.evolve.snapshot.v1", "mode": "paper-only"}
$ curl -fsS http://127.0.0.1:8765/research
{"schema_version": "zero.research.snapshot.v1", "mode": "paper-only"}
$ curl -fsS http://127.0.0.1:8765/hl/reconcile
{"schema_version": "zero.reconciliation.v1", "status": "not_configured", "risk_increasing_allowed": false}
$ curl -fsS http://127.0.0.1:8765/live/certification
{"schema_version": "zero.live_certification.v1", "mode": "dry_run", "passed": true}
$ curl -fsS http://127.0.0.1:8765/live/evidence
{"schema_version": "zero.live_evidence.v1", "live_mode": "refused", "evidence_hash": "sha256:..."}
$ curl -fsS http://127.0.0.1:8765/live/canary-policy
{"schema_version": "zero.live_canary_policy.v1", "summary": {"ready_for_canary": false, "next_step": "fix_live_preflight_before_canary"}}
$ scripts/live_canary_rehearsal.py http://127.0.0.1:8765 --mode refusal
zero live canary rehearsal: wrote artifacts/live-canary-rehearsal/... mode=refusal risk_ready=False attempted=True accepted=False
$ scripts/live_canary_exchange_evidence.py artifacts/live-canary-rehearsal/... hyperliquid-export.json
zero live canary exchange evidence: wrote artifacts/live-canary-rehearsal/.../exchange_evidence.json matched=0 accepted=0
$ scripts/live_canary_verify.py artifacts/live-canary-rehearsal/... --require-mode refusal --require-exchange-evidence
zero live canary verify: ok=True checks=... fail=0
$ scripts/live_canary_policy.py artifacts/live-canary-rehearsal/...
zero live canary policy: qualified=True publishable=False refusal_qualified=True next=keep_public_claim_at_refusal_proof
$ scripts/live_canary_operator.py http://127.0.0.1:8765 --mode refusal
zero live canary operator: ok=True bundle=artifacts/live-canary-operator/.../bundle exchange=True report=artifacts/live-canary-operator/.../operator_report.json
$ scripts/live_canary_operator_verify.py artifacts/live-canary-operator/...
zero live canary operator verify: ok=True checks=... fail=0
$ scripts/live_cockpit_drill.py http://127.0.0.1:8765
zero live cockpit drill: ok=True ready=False risk_allowed=False fail=0 output=artifacts/live-cockpit-drill/...
$ scripts/live_cockpit_drill_verify.py artifacts/live-cockpit-drill/...
zero live cockpit drill verify: ok=True checks=... fail=0
$ scripts/live_cockpit_drill_tamper_rehearsal.py artifacts/live-cockpit-drill/...
zero live cockpit drill tamper rehearsal: ok=True checks=3 fail=0
$ curl -fsS http://127.0.0.1:8765/immune
{"schema_version": "zero.immune.v1", "risk_increasing_allowed": false}
Install the latest release binary with checksum and attestation verification:
curl -fsSL https://raw.githubusercontent.com/zero-intel/zero/main/scripts/install.sh | bash
zero --versionThe installer downloads the GitHub Release asset for your OS, verifies
SHA256SUMS, verifies the GitHub artifact attestation, and installs zero to
~/.local/bin by default.
Or install the public Homebrew formula:
brew tap zero-intel/zero https://github.com/zero-intel/zero
brew install zero
zero --versionThe formula installs the zero CLI from the checksummed GitHub Release asset.
It does not use private package registries. Homebrew reinstall and rollback
commands live in docs/release.md.
zero-engine is also published on PyPI for agent/MCP installs:
uvx zero-engine --smoke
uvx --from zero-engine zero-mcp --smokeThe Rust operator terminal is published as zero-os on crates.io. The package
name is zero-os because zero is already taken on crates.io; the installed
binary is still zero:
cargo install zero-os
zero --versionContainer users can run the paper runtime directly from source:
docker build -t getzero/zero .
docker run --rm -p 8765:8765 -e PORT=8765 getzero/zeroDocker Hub is the primary public container path:
docker pull getzero/zero:0.1.2
docker run --rm -p 8765:8765 -e PORT=8765 getzero/zero:0.1.2The runtime remains paper-first by default; live operation stays behind explicit preflight gates. See docs/registry-launch.md for publication state, digests, and anonymous-pull evidence.
Use GitHub Codespaces or any devcontainer-compatible editor to open this repo
without installing Python, Rust, or just locally:
The container installs the editable engine package, Rust CLI dependencies, and the local docs gate. See .devcontainer/README.md.
Requirements: Python 3.11+, Rust stable, Cargo, and just.
git clone https://github.com/zero-intel/zero.git
cd zero
just bootstrap
just demo
just paper-api-smokeRun the paper API:
just paper-apiRun the CLI:
cd cli
cargo run -q -p zero-os -- --api http://127.0.0.1:8765 doctor
cargo run -q -p zero-os -- --api http://127.0.0.1:8765 run status
cargo run -q -p zero-os -- --api http://127.0.0.1:8765 run riskRun the full local gate:
just ciRun one paper runtime cycle:
PYTHONPATH="$PWD/engine/src" zero-engine-run \
--journal .zero/decisions.jsonl \
--runtime-bus .zero/runtime-bus \
--once \
--interval 0For the complete first-run path, see docs/first-10-minutes.md. For a reproducible terminal demo capture, run:
scripts/demo_capture.shMaintainers can also prove the publishable source tree works outside this checkout by copying it into a temporary directory, rerunning hardening, and smoking the paper API through the CLI:
just fresh-clone-rehearsalUse an installed release binary for the same capture:
ZERO_BIN="$(command -v zero)" scripts/demo_capture.shZERO is built around operational discipline, not activity.
- Paper mode is the default.
- Public examples must run without real funds.
- Live execution requires explicit environment configuration and preflight checks.
- Risk-reducing actions should remain low-friction.
- Risk-increasing actions should require deliberate operator confirmation.
- Journals and proof packets must be redacted before publication.
- Hosted custody is not part of the product.
Read the full model in docs/safety-model.md, docs/threat-model.md, and docs/failure-modes-autonomous-loop.md. Incident response is covered by docs/incident-runbooks.md and the public postmortem policy.
- CI, CodeQL, Secret Scan, and OpenSSF Scorecard run on public pushes.
- Release assets ship with checksums, SBOM/provenance metadata, attestations, release evidence, and Homebrew formula drift checks.
just release-preflightverifies public proof, package dry runs, release rehearsals, registry readiness, and formula consistency before tagging.
ZERO is open infrastructure plus free growth-mode intelligence. The future business model monetizes scale, retention, redistribution, support, and SLAs, not basic operator access while ZERO needs more verified operators.
| Open | Commercial |
|---|---|
| Runtime engine, safety gates, paper mode, local API, CLI, Docker/Railway deployment, public profile contracts, leaderboards, delayed snapshots, growth-mode realtime Intelligence access, docs, tests, and release tooling. | Future higher limits, deeper history, cohorts, benchmarks, commercial connectors, bulk exports, redistribution rights, support, reliability commitments, and SLAs. |
The open repository must stay useful without a ZERO-hosted control plane. The commercial product sells speed, scale, history, reliability, and intelligence access, not custody or basic runtime operation.
See docs/open-core-boundary.md and docs/zero-intelligence.md.
engine/ Python ZERO Runtime and paper API
cli/ Rust operator terminal
contracts/ Public API, Network, and Intelligence contract examples
examples/ Paper-trading examples and sample candles
docs/ Architecture, safety, deployment, release, and product docs
scripts/ Smoke tests, release packaging, Railway entrypoints, hardening gates
.github/ CI, CodeQL, secret scanning, Scorecard, issue and PR templates
ZERO is local-first, Railway-first, and Docker-compatible. Operators own their deployment project, secrets, exchange credentials, and runtime state.
- docs/local-development.md
- docs/railway-template.md
- docs/railway-deploy.md
- docs/distribution.md
- docs/release.md
- docs/release-verification.md
Start with the live
Contributor Issue Board or the GitHub
good first issue,
agent-eligible,
and
help wanted
queues.
Good first contribution areas:
- Declarative strategy runners that stay paper-first.
- Strategy examples that stay paper-first.
- Strategy plugins that return signals but leave execution and risk checks to ZERO.
- Market data adapters with deterministic tests.
- ZERO Network index, profile, and leaderboard pages over redacted public contracts.
- CLI diagnostics and replay views.
- Safety gate tests.
- Documentation and runbook improvements.
- Public Network and Intelligence contract examples.
Before opening a pull request:
just ciRead CONTRIBUTING.md, SECURITY.md, and GOVERNANCE.md.
Using a coding or design agent? Start with AGENTS.md and docs/agentic-contribution.md. Agent-authored changes should stay scoped, paper-first by default, and explicit about safety invariants.
For a 30-second agent smoke:
PYTHONPATH="$PWD/engine/src" python3 -m zero_engine.mcp --smoke
PYTHONPATH="$PWD/engine/src" scripts/mcp_transcript.py --checkMachine-readable entrypoints:
- llms.txt
- docs/llms.txt
- docs/llms-full.txt
- AGENTS.md
- Agent Commands
- Contributor Issue Board
- QA Onboarding Checklist
- Issue Templates
- OpenAPI Contract
- Agent Architecture
- Journal Integrity
- Memory Core
- Genesis
- Research Command Chain
- Decision Stack
- Evolve Harness
- MCP Server
- MCP Registry Packet
- MCP Transcript
- Architecture
- Agent Architecture
- Positioning
- First 10 Minutes
- Demo Terminal
- Proof Packs
- CLI Quickstart
- CLI Doctor Troubleshooting
- API
- Journal Integrity
- Memory Core
- Research Command Chain
- Decision Stack
- MCP Server
- MCP Registry Packet
- OpenAPI Contract
- API Compatibility
- Failure Modes
- Incident Postmortems
- Operator Context
- Deployment Identity
- Live Evidence
- Live Canary Operator
- Operator Isolation
- Strategy Plugins
- Market Data Adapters
- Hyperliquid Read-only
- ZERO Network
- ZERO Intelligence
- Model Gateway
- Production Readiness
- QA Onboarding Checklist
- Public Upgrade Plan
- Autonomous OS Plan
- Capability Gap Audit
- Agentic Contribution
- Contributor Issue Board
- Launch Scorecard
- Release Verification
- Roadmap
Apache-2.0. See LICENSE.