Skip to main content
Version: 0.2.15

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.
  • If you prefer authoring text, use the lossless x07text projection: write x07text, convert with x07 ast from-text --in mod.x07t --out mod.x07.json (output is canonical x07 fmt bytes), and render any module readable with x07 ast to-text. See x07text.

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 --prove|--coverage (proof artifacts plus explicit support posture)
  • Certificate-first review: x07 prove check, x07 trust certify, x07 review diff, x07 trust report

0.5) Version + compat + migration (do this early)​

New projects pin a compatibility mode in x07.json (project.compat, default "0.5"). If you open older projects or older package code, prefer mechanical migration over relying on legacy behavior:

x07 migrate --to 0.5 --check --input src/main.x07.json
x07 migrate --to 0.5 --write --input src/main.x07.json

For one-off debugging, you can override compatibility at the command level:

x07 run --compat 0.5

See: Compatibility contract and x07 migrate in Toolchain CLI.

0.6) Canonical patterns (loops, bytes/view, errors)​

  • Loops: use for for counted loops and while for scanning loops; reserve recursion for contract/verified code. for is strict-form x07AST; see AST authoring best practices (X07-FOR-0001).
  • Bytes/view: call-argument coercion exists, but prefer explicit bytes.view at library boundaries. bytes.view requires an identifier owner; for literals prefer bytes.view_lit (X07-BORROW-0001 + auto-fix via x07 fix).
  • Owned byte params: helper calls that take bytes consume the value. If a public byte param is reused across loops, helper calls, or postconditions, bind ["bytes.view","param"] once and pass ["view.to_bytes","param_v"] to owned-byte helpers.
  • Dependency roots: when imports fail, check x07.json.module_roots + x07.lock.json and inspect closure with x07 pkg tree.
  • Error propagation:
    • typed results (result_i32, result_bytes) use try
    • doc envelopes use try_doc (see Doc envelope)

0.7) Agent pitfalls (common failure modes)​

  • Loop forms (for): valid form is ["for","i",<start:i32>,<end:i32>,<body:any>] (X07-FOR-0001). Wrap multi-statement bodies in begin.
  • bytes.view literals/temporaries: bytes.view requires an identifier owner; use bytes.view_lit for literals and let tmp = <expr> for temporaries (X07-BORROW-0001, often auto-fixable via x07 fix).
  • Owned bytes reuse: passing a bytes param to a helper that expects owned bytes can move it. In composed library code, keep a bytes_view local and pass view.to_bytes copies into repeated helper calls.
  • Borrow-union returns: returning bytes_view from if/option/result branches that borrow from different owners is usually rejected; return owned bytes (copy) instead.
  • XTAL brands: when a public byte boundary is branded in src/*.x07.json, the corresponding spec/*.x07spec.json operation signature must also carry the same brand / result_brand ids (and generated property wrappers will inherit them). See docs/toolchain/xtal.md and docs/examples/agent-gate/xtal/workflow-graph/.
  • Dependency roots: module-not-found errors are usually missing module_roots or missing/stale locks; use x07 pkg tree / x07 pkg provides and re-run x07 pkg lock --check --offline.
  • set is an expression: ["set", x, e] evaluates to the assigned value, so statement-shaped ["if", c, ["set", x, e], 0] fails branch unification when x is not i32. Use ["set0", x, e] (returns 0 as i32) for statement assignments.
  • std.hash_map is fixed capacity: the slot table never grows; inserting a new key into a full map traps with map_u32 full. Create maps with std.hash_map.with_capacity_u32(expected) instead of guessing a cap_pow2.
  • vec_u8 is accumulate-then-freeze: build with std.vec.push / std.vec.extend_bytes (rebinding the move-only handle each call), then freeze once with std.vec.as_bytes. No random reads while growing — for read-while-grow state keep a bytes arena and read it with std.codec.read_u32_le.
  • Two concats: the builtin bytes.concat takes owned (bytes, bytes) and consumes both; std.bytes.concat takes views. Prefer std.vec.extend_bytes or std.bytes.concat to avoid accidental moves.
  • Generics need explicit instantiation: generic stdlib calls (std.heap, std.btree_map, std.deque, ...) require explicit tapp / tys type arguments; there is no inference.
  • Integer literals are i32: 0xFFFFFFFF overflows the literal range; write all-ones sentinels as -1.

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.doc_v1, x07.wasm.core_v1, safe patching, etc). The active surface is core editing, packages, and WASM.

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 actions, call x07.ecosystem.status_v1 so the client sees which packs are actually enabled on the current machine.

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

mkdir ./my-mcp-http-tasks
cd ./my-mcp-http-tasks
x07 init --template mcp-server-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; copied from the toolchain when init ran)
  • .agent/skills/ (skills pack; copied from the toolchain when init ran)
  • src/ (a minimal program)
  • tests/tests.json + tests/smoke.x07.json (a harness smoke test)

Templates (agentic starting points)​

Use templates when the shape matches your project: they include pinned local deps + lockfiles, so you can iterate offline without guessing.

  • Typed CLI (ext-cli + specrows): x07 init --template cli
  • File I/O with explicit caps (run-os-sandboxed): x07 init --template fs-tool (defaults to the sandbox profile)
  • JSON reporting (DataModel → canonical JSON): x07 init --template json-report (see JSON reporting)
  • Spec-first pure XTAL starter: x07 init --template xtal-pure
  • Certifiable pure XTAL starter: x07 init --template xtal-verified

Offline sanity check (for dependency hydration):

x07 run --offline
x07 pkg lock --check --offline

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*).
  • If the project will be certified, set project.operational_entry_symbol on the current manifest line (x07.project@0.5.0). Strong trust profiles certify that operational entry and reject proof-only surrogate entries.

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 certificate-backed 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. Unknown-symbol errors include did-you-mean suggestions, and x07 run failure reports embed the structured diagnostics — parse the report instead of scraping stderr.

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

By default, the test harness runs non-PBT tests. If the suite includes property-based tests, run the full suite with:

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

To run only property-based tests, use x07 test --pbt --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.
  • Multi-file patchsets: x07 patch apply --in <patchset.json> --repo-root . --write applies an x07.patchset@0.1.0 across specs, source modules, and manifests.

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 with proof inventory, assumptions, and runtime/boundary evidence)

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

Local path deps (offline-first):

# Add a dependency, but keep it as a local path (no registry fetch needed):
x07 pkg add ext-cli@VERSION --path .x07/deps/ext-cli/VERSION --sync

# Forbid any network during lock checks / hydration:
x07 pkg lock --check --offline

Notes:

  • x07 pkg add edits x07.json. With --sync, it also updates x07.lock.json.
  • Canonical project manifests use x07.project@0.5.0. x07.project@0.2.0, x07.project@0.3.0, and x07.project@0.4.0 are accepted for legacy manifests, and certification surfaces use the x07.project@0.4.0 fields such as project.operational_entry_symbol (still present in x07.project@0.5.0).
  • To migrate a legacy manifest to the current schema line, run x07 project migrate --write --project x07.json.
  • 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 builtin forms (example: bytes.len, task.scope_v1, budget.scope_v1), use x07 doc <name> (or force builtin resolution with x07 doc --builtin <name>). For the full reference (including syntax forms), use x07 guide. See: Prelude & names.
  • 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 --registry <URL> (alias: --index <URL>), or set a default in .x07/config.json / x07.config.json. 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).
  • After upgrading the toolchain, if old locks reference incompatible package versions, use x07 pkg repair --toolchain current.
  • If you must force a transitive dependency version, use project.patch in x07.json on the current x07.project@0.5.0 manifest line.
  • 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. Requirements are exact versions (base@0.1.5) or SemVer ranges (base@>=0.1.5 <0.2.0); ranges resolve to the highest satisfying version at lock time and the lockfile freezes the choice.
  • 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). Stdlib exports include behavioral summaries (what the function does, not just its signature), and lookup is fuzzy — near-miss names resolve with suggestions.
  • 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)
  • json-report (typed CLI → DataModel → canonical JSON report)
  • archive-safe-extract/zip-hello (safe ZIP extraction; hardened defaults)
  • archive-extract-to-fs/zip-hello (streamed extraction to filesystem)
  • 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)​