Skip to main content
Version: 0.1.41

Running programs (canonical): x07 run

x07 run is the single front door for executing X07 programs. It selects the appropriate runner based on the selected profile and prints a machine-readable JSON report.

Choose what to run​

Exactly one target mode is used:

  • x07 run (no flags): auto-discovers a project manifest (x07.json or a single *.x07project.json) by walking up from the current directory.
  • x07 run --project path/to/x07.json: run a specific project manifest (+ lockfile).
  • x07 run --program path/to/main.x07.json: compile+run a single file (module roots are inferred unless --module-root is provided).
  • x07 run --artifact path/to/exe: run a precompiled executable (run-os only; runner output only; no project metadata).

Auto-repair (default)​

By default, x07 run performs a bounded repair loop on the entry program before compiling:

  • canonicalize formatting
  • lint (world-aware)
  • apply any JSON Patch quickfixes (x07diag)
  • repeat up to --repair-max-iters (default: 3)

Control it with:

  • --repair=write (default): write repairs back to the source file
  • --repair=memory: stage a repaired copy under .x07/repair/_staged/ and compile/run that
  • --repair=off: disable auto-repair

When using --report wrapped, the wrapper includes a repair summary object when repair is enabled.

Executable I/O framing (advanced)​

Executables produced by the X07 runners use a simple byte framing:

  • stdin: u32_le(len) then len bytes
  • stdout: u32_le(len) then len bytes
  • stderr: JSON stats

x07 run handles this framing automatically.

This “framed I/O” executable ABI is designed for machine-driven execution. If you want a normal end-user CLI binary (no framing, standard argc/argv, raw stdout) use x07 bundle.

For almost all end-user usage, pick intent-driven profiles in your project (x07.json.default_profile + x07.json.profiles) and use:

  • x07 run (uses default_profile)
  • x07 run --profile os
  • x07 run --profile sandbox

Profiles resolve to a world (run-os or run-os-sandboxed) plus optional policy and resource defaults.

If --profile is not provided, x07 run uses default_profile from the project manifest when present, otherwise it defaults to os.

Runner selection​

By default, x07 run chooses the runner from the selected profile (x07-os-runner for OS profiles).

You can force OS runner selection with --runner os or --os.

Provide input bytes​

Input selection (highest precedence first):

  1. --input path/to/input.bin
  2. --stdin (reads all stdin bytes)
  3. --input-b64 <BASE64>
  4. trailing args after -- (encoded as argv_v1)
  5. profiles.<name>.input (project-relative path)
  6. no input (empty bytes)

Example: pass CLI-style args via argv_v1:

x07 run -- tool --help

Policies (run-os-sandboxed)​

run-os-sandboxed requires a base policy file:

  • via profile: profiles.sandbox.policy
  • or via CLI: x07 run --profile sandbox --policy path/to/policy.json

To generate a schema-valid starting policy, use x07 policy init --template <...> and then extend it for your app.

Convenience overrides for net/filesystem allowlists are available only in run-os-sandboxed and materialize a derived policy under .x07/policies/_generated/:

  • --allow-host host:port[,port...] / --deny-host host:*|host:port[,port...] (deny wins)
  • --allow-read-root /abs/or/rel/path / --allow-write-root /abs/or/rel/path

Note: --allow-host requires explicit ports; * is accepted only by --deny-host.

Sandbox backend (run-os-sandboxed)​

run-os-sandboxed defaults to sandbox_backend=vm and fails closed if a VM boundary can’t be provided.

Control it with:

  • CLI: --sandbox-backend auto|vm|os|none
  • CLI: --i-accept-weaker-isolation (required when the effective backend is os/none)
  • Env: X07_SANDBOX_BACKEND / X07_I_ACCEPT_WEAKER_ISOLATION

Compilation and resource knobs​

Common flags:

  • --cc-profile default|size
  • --max-c-bytes <BYTES>
  • --compiled-out <PATH> (write the produced runner executable; framed I/O)
  • --solve-fuel <N>, --max-memory-bytes <N>, --max-output-bytes <N>, --cpu-time-limit-seconds <N>
  • --auto-ffi / --no-auto-ffi (OS worlds; collect/apply C FFI flags from dependencies)

Distribute a native executable (canonical): x07 bundle​

x07 bundle produces a native CLI executable that can be run directly (no framed I/O).

Examples:

# Bundle an OS-world CLI binary:
x07 bundle --profile os --out dist/mytool
./dist/mytool --help

# Bundle a VM-backed sandbox bundle (run-os-sandboxed):
x07 bundle --profile sandbox --out dist/mytool

# Bundle a legacy policy-only sandbox bundle (weaker isolation; no VM boundary):
x07 bundle --profile sandbox --sandbox-backend os --i-accept-weaker-isolation --out dist/mytool

For --profile sandbox with sandbox_backend=vm, the output is a host-native launcher plus a sidecar directory dist/mytool.vm/.

The sidecar includes a versioned manifest (x07.vm.bundle.manifest@0.2.0) that pins the VM backend and the expected guest digest.

The bundled binary encodes argc/argv to argv_v1 input bytes and writes the program output bytes directly to stdout.

Sandbox bundle environment overrides​

For sandbox bundles, the generated native wrapper always forces sandboxing on:

  • X07_WORLD=run-os-sandboxed
  • X07_OS_SANDBOXED=1

Other X07_OS_* environment variables embedded into the wrapper are treated as defaults and may be overridden by the parent process. This enables per-invocation policy injection (for example, spawning a sandboxed worker with tool-specific filesystem/network allowlists).

Reports (stdout + optional file)​

x07 run always prints a JSON report to stdout. You can also write the same bytes to a file with --report-out <PATH>.

Report modes:

  • --report runner (default): pass through the runner JSON (spec/x07-os-runner.report.schema.json)
  • --report wrapped: wrap the runner JSON in spec/x07-run.report.schema.json (schema_version: "x07.run.report@0.1.0")

Runtime traps (AST pointers)​

When a program traps at runtime, the trap message may include an x07AST pointer like ptr=/solve/... when available. Use that pointer to locate the corresponding node in the *.x07.json source.

Common failure: unknown module (missing deps)​

If compilation fails because a module can’t be resolved, the report will have:

  • compile.ok: false
  • compile.compile_error containing something like Parse: unknown module: "ext.cli" (searched: ext/cli.x07.json)

Fix:

  • discover candidates: x07 pkg provides <module-id>
  • for packages: add the dependency (x07 pkg add <name> --sync, or pin with x07 pkg add <name>@<ver> --sync) so x07.lock.json provides module roots, or
  • for standalone --program runs: ensure the module exists under a --module-root directory.