Docs

Install guide

Prerequisites: cargo, bun, and omp on PATH. If omp is missing, the installer fetches it from https://omp.sh/install and stops — login stays yours.

git clone https://github.com/fedoragobrowse-design/somp.git ~/code/somp && ~/code/somp/install.sh

The installer builds the release CLI, links ~/.local/bin/somp, writes the somp-omp wrapper, seeds ~/.config/somp/config.yaml if absent, then verifies (somp doctor + extension bundle). Idempotent — safe to re-run. It never touches ~/.omp, your skills, MCP servers, or shell rc.

Commands

somp	Opens the governed omp TUI (normal omp + sOMP extension)
somp-omp	Same via the wrapper; passes all flags (e.g. --model, --resume) through
omp	Plain omp — untouched, ungoverned, exactly as upstream ships it
somp level [strict|standard|off]	Show or set the sandbox protection level
somp update [--check]	Pull + rebuild from your repo only (fedoragobrowse-design/somp); --check reports without changing anything
somp doctor	Tier check: KVM, bwrap userns, nft
somp session up/exec/destroy/show	Long-lived session VM lifecycle
somp dispatch --task-file T.md	One governed subagent run: stage → exec → git diff → destroy
somp policy propose/show	Guard egress widening: propose; a human approves out-of-band
somp bench	Raw-JSON benchmarks (host proxies until Firecracker E2E lands)

Configuration

~/.config/somp/config.yaml. Every field has a fail-closed default except guard.model_host / model_port — no default, because inventing one would aim boxes at the wrong provider.

aiec:
  base_url: "https://127.0.0.1:18443"
  key_file: /home/you/.config/aiec/api-key
  api_key_env: "AIEC_API_KEY"

session:
  image: "somp-guest"   # built by guest/build-guest.sh
  cpus: 2
  mem_mb: 1024
  disk_mb: 4096
  ttl_s: 82800          # < AIec MAX 86400s

guard:
  template: "model-only"
  model_host: "api.example-model.com"  # REQUIRED: replace
  model_port: 443

srt:
  settings_path: "guest/srt-settings.json"

SOMP_LEVEL in the environment overrides the configured level; unknown values fail closed.

Inside the TUI

The status bar shows sandbox 🛡️ STRICT (or 🔶 STANDARD / ⚠️ OFF). /somp-status prints mode, level, and tier evidence; /somp-level [strict|standard|off] switches live. Resume governed with somp-omp --resume <id> — plain omp --resume reloads ungoverned, and the extension says so on shutdown. All built-in / commands work identically under somp-omp; only task is intentionally blocked (use somp_task).

Updating

somp update pulls only fedoragobrowse-design/somp (exact-origin gate — lookalikes refused), branch-aware, then rebuilds + reinstalls. omp update is upstream's channel and never breaks the wrapper: it execs omp from PATH with an explicit -e flag, and the installer's bundle check fails loudly if the seam ever drifts.

Known limits

Warm-start <1s and per-subagent RSS are unproven (need Firecracker E2E); host-side srt numbers are proxies. The JEV bash gate is a tested pure function, not yet wired live. The full standing list lives in docs/UNPROVEN.md in the repo — failures are loud and fail-closed, never silent ungoverned fallbacks.