x07-os-run

x07-os-run

Prefer x07 run --profile os / x07 run --profile sandbox (or x07 run --world run-os*) for normal execution. Use x07-os-runner directly only when you need runner-specific flags (policy debugging, auto-FFI toggles, explicit compiled artifact paths) or when you are debugging runner behavior.

Use this skill when you need real OS I/O (fs/net/process/time) via run-os or policy-enforced execution via run-os-sandboxed.

Canonical commands (recommended: x07 run)

• Run the current project (unsandboxed):

  • x07 run --profile os
  • (equivalently) x07 run --world run-os

• Run a project explicitly (unsandboxed):

  • x07 run --project x07.json --world run-os

• Run sandboxed (requires an explicit policy):

  • x07 run --project x07.json --world run-os-sandboxed --policy run-os-policy.json

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

  • x07 run --profile os -- tool --help

• Generate a schema-valid base policy:

  • x07 policy init --template cli
  • x07 policy init --template http-client
  • x07 policy init --template web-service
  • x07 policy init --template fs-tool
  • x07 policy init --template sqlite-app
  • x07 policy init --template postgres-client
  • x07 policy init --template worker
  • x07 policy init --template worker-parallel

• Materialize a derived policy with explicit destinations (only in run-os-sandboxed):

  • x07 run --project x07.json --world run-os-sandboxed --policy .x07/policies/base/http-client.sandbox.base.policy.json --allow-host example.com:443
  • x07 run --project x07.json --world run-os-sandboxed --policy .x07/policies/base/http-client.sandbox.base.policy.json --deny-host example.com:*

• Run a single program (when not using a project manifest):

  • x07 run --program src/main.x07.json --world run-os --module-root src

Expert backend commands (x07-os-runner)

• Run a program (unsandboxed):

  • x07-os-runner --program src/main.x07.json --world run-os --module-root src

• Run a project (unsandboxed):

  • x07-os-runner --project x07.json --world run-os

• Run sandboxed (requires an explicit policy):

  • x07-os-runner --program src/main.x07.json --world run-os-sandboxed --policy run-os-policy.json --module-root src

Policy

Policies are a starting point. Generate one from a template, then extend it deliberately for your app (roots, env, subprocess allowlists, limits). For net-enabled templates, keep net.allow_hosts empty in the base policy and use x07 run --allow-host to materialize auditable derived policies for specific destinations.

Output contract

• x07 run in run-os* worlds prints an x07-os-runner.report@... JSON report to stdout (pass-through).
• x07-os-runner prints the same report shape when invoked directly.

In both cases:

• Use the process exit code for pass/fail.
• Parse the JSON for schema_version, mode, world, and base64-encoded output bytes.