# X07 Os Run

> Expert backend for run-os / run-os-sandboxed execution via x07-os-runner. Prefer `x07 run --profile os` / `x07 run --profile sandbox`. Use when this capability is needed.

- Skill: `tomevault-io/x07-os-run` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/x07-os-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/x07-os-run/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/x07-os-run

---


# x07-os-run

Prefer `x07 run --profile os` / `x07 run --profile sandbox` for normal execution. `x07-os-runner` is an internal component behind the `x07` facade; its CLI is not part of the supported end-user surface.

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`
  - `x07 run --profile os`

- Run a project explicitly (unsandboxed):
  - `x07 run --project x07.json --profile os`

- Run sandboxed (requires an explicit policy):
  - `x07 run --project x07.json --profile sandbox --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 --profile sandbox --policy .x07/policies/base/http-client.sandbox.base.policy.json --allow-host example.com:443`
  - `x07 run --profile sandbox --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 --module-root src`

## Expert backend (`x07-os-runner`)

`x07-os-runner` implements OS execution for `x07 run` / `x07 bundle`. Treat it as internal and prefer `x07` commands above.

## 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).
- The underlying OS runner emits the same report shape.

In both cases:
- Use the process exit code for pass/fail.
- Parse the JSON for `schema_version`, `mode`, `world`, and base64-encoded output bytes.

## Repro bundles (compile-time)

If compilation fails in CI or a restricted environment, generate a portable compile repro bundle:

- `x07 repro compile --project x07.json`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/x07lang) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->