Skip to main content
Version: 0.1.79

Agent quickstart (learn X07 from scratch)

This page is a single entry point for LLM agents. Use the published agent portal endpoints as the canonical source of schemas/skills/examples (see Agent contracts).

If you want a single copy/paste prompt to bootstrap a new project, use: Agent initial prompt.

If you find a documentation gap, check the toolchain source directly in GitHub:

0) The mental model​

  • X07 source is x07AST JSON (*.x07.json), not text.
  • The toolchain is JSON-first: diagnostics, patches, and reports are structured.
  • Programs run in worlds (fixture or OS); OS worlds are run-os and run-os-sandboxed.

High-level primitives to learn early (the “one whole system”):

  • Streaming pipes: std.stream.pipe_v1 (deterministic, budgeted streaming composition)
  • Branded bytes: bytes@B + std.brand.* (typed boundary encodings)
  • Structured concurrency: task.scope_v1 (no orphan tasks; slots/select)
  • Record/replay: std.rr + rr scopes (OS → deterministic cassette)
  • Budget scopes: budget.scope_v1 (localize cost contracts; arch-driven budgets)
  • Contracts tooling: x07 arch check, x07 schema derive, x07 sm gen (pinned contracts → deterministic checks/generation)
  • Property-based testing: x07 test --pbt + x07 fix --from-pbt (counterexample → deterministic regression)
  • Function contracts + verification: requires / ensures / invariant + x07 verify --bmc|--smt (bounded proof artifacts)
  • Review + trust artifacts: x07 review diff + x07 trust report (human reviewable “intent-level” diff + trust report)

1) Install and verify the toolchain​

  • Install with x07up (recommended).

Prerequisites (macOS / Linux):

  • sh + tar
  • curl or wget (used for downloads)
  • a sha256 tool (sha256sum, shasum, or openssl) for installer verification
  • for OS worlds / native deps (for example ext-curl-c): a C toolchain and libcurl headers (x07 doctor reports missing deps)

macOS / Linux (CI-safe, no profile edits, JSON report):

curl -fsSL https://x07lang.org/install.sh | sh -s -- \
  --yes \
  --channel stable \
  --no-modify-path \
  --json
export PATH="$HOME/.x07/bin:$PATH"

If you are not in CI, you can omit --no-modify-path and the installer will attempt to persist the PATH change.

Verify:

x07 --help
x07 run --help
x07up show --json
x07 --cli-specrows

If you plan to use OS worlds (run-os*) with native deps (for example ext-net / ext-curl-c / ext-sockets-c), run:

x07 doctor

See also: Install.

MCP: install the official X07 MCP server (optional)​

If your agent runtime supports MCP (Model Context Protocol), install the official X07 MCP server: io.x07/x07lang-mcp. It lets an MCP client drive the local X07 toolchain via token-efficient core tools plus capability-gated ecosystem tools (x07.ecosystem.status_v1, x07.pkg.provides_v1, x07.wasm.core_v1, x07.web_ui.exec_v1, x07.device.exec_v1, x07.app.exec_v1, lp.query_v1, lp.control_v1, safe patching, etc).

Download the published bundle from GitHub releases:

  • Repo: https://github.com/x07lang/x07-mcp
  • Release tag pattern: x07lang-mcp-v<MAJOR.MINOR.PATCH> (download the latest published release on the releases page)
  • Files: x07lang-mcp.mcpb and x07lang-mcp.mcpb.sha256.txt

Verify (macOS / Linux):

expected="$(cat x07lang-mcp.mcpb.sha256.txt)"
got="$(shasum -a 256 x07lang-mcp.mcpb | awk '{print $1}')"
test "$got" = "$expected"

Configure your MCP client:

  • If your client supports .mcpb, install the bundle.

  • If your client requires a command/args server definition, extract the bundle and run the router from the bundle root:

    unzip -q x07lang-mcp.mcpb -d x07lang-mcp.bundle

    Use:

    • command: .../x07lang-mcp.bundle/server/x07lang-mcp
    • cwd: .../x07lang-mcp.bundle (so config/mcp.server.json + out/mcp-worker resolve)
    • env (recommended): X07_MCP_X07_EXE=/absolute/path/to/x07 (command -v x07)

Before optional wasm or platform actions, call x07.ecosystem.status_v1 so the client sees which packs are actually enabled on the current machine. When a workflow needs safe structured lifecycle actions, use the official MCP server path (lp.control_v1 when the platform pack is enabled) instead of private shell glue to x07-platform.

For control-room style clients, keep release-candidate or workspace state in the client and join it to the public lifecycle result contracts (lp.control.action.result, lp.deploy.query.result, lp.environment.list.result, lp.incident.query.result, lp.regression.run.result) rather than parsing shell output. See Platform (x07lp).

If you are creating a new HTTP/SSE MCP server project that needs long-running tool calls or task polling, start from:

x07 init --template mcp-server-http-tasks --dir ./my-mcp-http-tasks

That scaffold still comes from x07-mcp; x07 only owns the delegation path and the surrounding project bootstrap.

2) Create a project (canonical starting point)​

mkdir myapp
cd myapp
x07 init

x07 init creates both the project skeleton and the agent kit:

  • x07.json (with os and sandbox profiles)
  • x07.lock.json
  • x07-toolchain.toml (pins stable and declares docs + skills)
  • AGENT.md (self-recovery guide + canonical commands)
  • .agent/docs/ (offline docs; linked to the installed toolchain when available)
  • .agent/skills/ (skills pack; linked to the installed toolchain when available)
  • src/ (a minimal program)
  • tests/tests.json + tests/smoke.x07.json (a harness smoke test)

x07.json notes (common failure mode)​

  • The root world field is required (it’s used as a fallback when no run profile is selected).
  • For multi-profile projects, set the root world to the solve-* world you want for deterministic lint/repair (for example solve-pure), and run OS worlds via profiles (run-os*).

Contracts-by-example (copy/paste)​

If your project uses pinned rr policies, archive policies, DB migrations, or arch-driven budgets, start from a schema-valid example arch/ tree:

  • docs/examples/contracts_project/ (copy its arch/ into your project root)

If you are creating a publishable package repo (for x07 pkg publish), use x07 init --package instead of x07 init.

If you want the smallest certificate-first pure project instead of the default app skeleton, start from:

x07 init --template verified-core-pure

That template wires arch/, smoke/PBT tests, and verified_core_pure_v1 so you can go straight to x07 trust profile check and x07 trust certify.

If you want the sandboxed Milestone B line instead, use:

x07 init --template trusted-sandbox-program

For a capsule-only starting point, use:

x07 init --template certified-capsule

See also: Available skills.

3) The core loop: run → test (auto-repair)​

Run:

x07 run

x07 run runs the canonical auto-repair loop by default (format → lint → quickfix, repeatable). Use --repair=off when debugging, or --repair=memory to stage repairs without editing source files.

See: Running programs.

Diagnostics tip: many compiler errors include ptr=/... (a JSON Pointer into your x07AST) and sometimes moved_ptr=/... for ownership errors. Use x07 ast get --in src/main.x07.json --ptr /... to extract the failing node without manually counting indexes.

If you hit a compiler budget error (for example Budget: max locals exceeded or Budget: AST too large), see: Compiler limits.

Dependency tip: when compilation fails due to a missing module and prints hint: x07 pkg add ... --sync, x07 run can apply the hinted package add automatically and retry.

Run report tip: in run-os, the rr_* counters in x07 run --report ... are record/replay adapter stats and are not a count of real OS network requests.

If your program expects CLI arguments via argv_v1, pass them after -- and x07 run will encode them into input bytes:

x07 run -- tool --help

Run the deterministic harness (repo-defined suites):

x07 test --manifest tests/tests.json

For non-mutating, whole-project validation (full import graph + typecheck + backend-check, no emit), run:

x07 check --project x07.json

If the suite includes property-based tests, run:

x07 test --all --manifest tests/tests.json

If PBT finds a counterexample, convert it into a committable regression test:

x07 fix --from-pbt target/x07test/pbt/<...>/repro.json --write

See: Property-based testing and PBT repro → regression test.

4) Repairs: quickfixes and patches​

Two canonical repair mechanisms:

  • Quickfixes: x07 fix applies the tool-provided quickfix JSON patches deterministically.
  • Explicit patches: x07 ast apply-patch applies RFC 6902 JSON Patch.

Note: x07 run, x07 build, and x07 bundle apply quickfixes automatically by default (--repair=...). Use the explicit loop below when you want raw diagnostics or tighter control.

Example loop:

x07 lint --input src/main.x07.json
x07 fix --input src/main.x07.json --write
x07 lint --input src/main.x07.json

See: Repair loop.

If you need a human-reviewable artifact for an agent patchset, use:

  • x07 review diff (semantic diff; HTML)
  • x07 trust report (budgets/worlds/nondeterminism summary)
  • x07 trust certify (certificate bundle for verified_core_pure_v1 projects)

See: Review & trust artifacts.

5) Learn the language​

Key x07AST shapes:

  • expression call: ["head", arg1, arg2, ...]
  • identifier: "std.bytes.len"

6) Packages (external dependencies)​

Discover packages and versions:

Add a dependency:

# Add the latest non-yanked version from the index:
x07 pkg add NAME --sync

# Or pin explicitly:
x07 pkg versions NAME
x07 pkg add NAME@VERSION --sync

# Remove a dependency:
x07 pkg remove NAME --sync

Notes:

  • x07 pkg add edits x07.json. With --sync, it also updates x07.lock.json.
  • Canonical project manifests use x07.project@0.3.0. x07.project@0.2.0 is accepted for legacy manifests, but project.patch requires @0.3.0.
  • x07 pkg add NAME@VERSION is safe to re-run: if the same dep+version already exists, it succeeds as a no-op. If the dep exists at a different version, pick a version explicitly and update the project deps.
  • If a module import fails and you don’t know which package provides it, use x07 pkg provides <module-id>.
  • If you’ve added a package but don’t know which modules it exports, use x07 doc <package-name> (example: x07 doc ext-net).
  • For builtin std.* modules (file: <builtin>), use x07 doc std.<module> (example: x07 doc std.bytes).
  • For package-provided std.* modules, run x07 doc <module-id> --project x07.json after adding the package (example: after x07 pkg add ext-net --sync, run x07 doc std.net.tcp --project x07.json).
  • For special forms (pipes, task.scope_v1, budget.*) and non-module builtins (example: std.brand.*), use x07 guide + linked docs pages (not x07 doc).
  • For structured encodings, prefer branded bytes + validators over ad-hoc parsing (see std.brand.cast_view_v1 / std.brand.cast_view_copy_v1 in x07 guide and meta.brands_v1 in schema-derived modules).
  • For streaming transforms, prefer std.stream.pipe_v1 and std.io.bufread over manual loops (more predictable allocations; fewer borrow/ownership hazards).
  • x07 pkg lock defaults to the official registry index when fetching is required; override with --index or forbid network with --offline.
  • In CI, run x07 pkg lock --project x07.json --check.
  • When the index can be consulted, x07 pkg lock --check also fails on yanked dependencies and active advisories unless explicitly allowed (--allow-yanked / --allow-advisories).
  • If you must force a transitive dependency version, use project.patch in x07.json (requires x07.project@0.3.0).
  • Some packages may declare required helper packages via meta.requires_packages. When present, x07 pkg lock can add and fetch these transitive deps, but agents should treat the capability map + templates as canonical so the dependency set is explicit.
  • Examples of transitive helpers: ext-net pulls ext-curl-c/ext-sockets-c/ext-url-rs, and ext-db-sqlite pulls ext-db-core (which pulls ext-data-model).

If you hit a dependency version conflict, the canonical repair loop is:

x07 pkg versions NAME
x07 pkg remove NAME --sync
x07 pkg add NAME@VERSION --sync

See also: Packages & projects.

7) World selection (OS worlds)​

  • run-os: real OS adapters (disk/network/time/env/process)
  • run-os-sandboxed: policy-gated OS adapters (defaults to a VM boundary; still not a hardened sandbox if you mount secrets or enable networking)

For run-os-sandboxed, start from a schema-valid policy template instead of hand-writing JSON:

x07 policy init --template worker --out policy/sandbox.base.json --mkdir-out

Prefer profiles (x07.json.default_profile + x07.json.profiles) so agents usually run:

  • x07 run (project default)
  • x07 run --profile os / x07 run --profile sandbox (explicit intent)

See: OS worlds.

8) Machine-first discovery surfaces​

  • CLI surface: x07 --cli-specrows
  • Schemas: spec/*.schema.json (and the synced copies on x07lang.org under /agent/.../schemas/)
  • External packages index: GET /agent/latest/packages/index.json on x07lang.org
  • Offline docs: x07up docs path --json
  • Local module inspection: x07 doc <module-or-symbol> (example: x07 doc std.bytes)
  • Local package inspection (project deps): x07 doc <package-name> (example: x07 doc ext-net)
  • Built-in reference guide: x07 guide

9) Known-good reference projects (copy/paste)​

The x07 repo ships CI-gated example projects under docs/examples/agent-gate/:

  • cli-newline (pure CLI payload parsing)
  • cli-ext-cli (CLI args via ext-cli + argv_v1)
  • web-crawler-local (sandboxed OS networking + --allow-host, against a local fixture site)

For the canonical package-focused set (examples + scenarios), see: Agent workflow.

See also: Patch-based recipes.

10) By-example tutorials (long-form)​