First run

First run

skep onboard takes a new machine to a governed chat in five steps. Until you approve a policy baseline, a fresh home asks you before every governed action.

Install and first run
$ pipx install skep && skep onboard

Not installed yet, or no sandbox backend? Start at Install.

skep onboard

The five steps

Plain prompts, no full-screen interface, so it works over SSH. Each step writes a record, and running it again resumes at the first step that is not done.

What skep onboard asks and writes
StepWhat it asksWhat it does
① model Provider, model, endpoint, and the name of the environment variable that holds the API key. Never the key itself. Tests the provider already configured and keeps it if it works; otherwise looks for a local Ollama. Makes one test call and prints where prompts will go: this machine, or a named host.
② work directory A path. The default is ~/workspace, created if missing. Registers it as a project and infers its verify command from the repository's own entry point, when it has one.
③ sandbox auto, podman or none. Records the backend. auto is bubblewrap on Linux and Seatbelt on macOS.
④ template builder (the default), operator or assistant, each shown as an allow / ask / deny table. assistant cannot edit code. Locks the one you choose as the policy baseline, after you type yes.
work without asking Once: may skep work in the work directory without asking? Enter means no. Not offered with no sandbox or no verify command, and it says why. A typed y turns on unlocked mode for that one project: inside the sandbox, skep starts runs, answers routine command questions and lands patches its own re-run of your tests confirmed, on skep/* branches. Merging to main, pushes, PRs, messages, policy changes and new network hosts still ask.
⑤ role One of the same three names. Records the role new chats open in.

After step ⑤ it connects to skep serve, or starts it, and opens skep chat. Pass --no-chat to stop before that.

Every prompt has a flag, so the whole run can be scripted. --yes takes the default for any step you gave no flag for and skips the typed yes. It never turns on working without asking; --unlocked does. --provider takes mock, ollama, openai-compatible, or a preset id from skep provider presets.

skep onboard, scripted
skep onboard --provider mock --workdir ~/workspace --sandbox auto --template builder --role builder --yes --no-chat
① model
  test: mock provider: no call made
  egress: mock — no call leaves this machine
② work directory
  created ~/workspace
  registered as project workspace
  verify_command: none inferred (no entry point) — re-verify falls back
  to the worker's own command until one is pinned
③ sandbox
  auto: rings live: floor, locked baseline, capability layer, sandbox (bubblewrap)
④ template
policy baseline: builder
# cut here: the allow / ask / deny table (39 rows) and its settings
  baseline locked: builder sha256 01db10ac4fc3
⑤ role
  role: builder (recorded in ~/.skep/first_run.json)
onboarded — check any time: skep onboard --check
captured: skep onboard with the mock provider (no model call, no key), throwaway HOME shown as ~, Fedora, 2026-11-18

Policy baseline

A fresh home asks until a baseline is locked

Step ④ is the one that changes how skep decides. Before it, nothing is allowed by rule.

  • With no baseline approved, every governed action in the policy engine's scopes gets the verdict ask, reason no_baseline. The floor still denies first: a worker's git push is refused whatever you answer.
  • A template is a starting set of rules. skep policy explain builder prints one as a table before you lock anything.
  • Locking writes the baseline and a lock for it. A hand edit afterwards is reported as baseline_tampered: every action asks until you run skep policy approve --reapprove, which shows the difference first.
  • Without the guided run, skep policy approve --template builder locks a baseline on its own.
  • If you answered none at the sandbox step, the baseline is locked with every allowed write turned into a question.
skep policy baseline status
# on a fresh home
skep policy baseline status
baseline: none approved
# after skep onboard
skep policy baseline status
baseline: builder approved 2026-11-19T00:23:26Z sha256 01db10ac4fc3
captured: skep policy baseline status, before and after onboarding, throwaway home, 2026-11-18

skep onboard --check

Check the setup at any time

A read-only check: skep doctor, then the onboarding checks, then where your data goes. It exits 0 only when every check is ready.

On top of what skep doctor reports, it checks that:

  • the baseline still matches its lock;
  • the locked baseline is the one your template locks under the current sandbox;
  • the policy engine is on for every scope;
  • the chosen sandbox backend is present;
  • the work directory is writable, and the model is reachable;
  • all five steps are done.

skep doctor itself reports each engine's binary and sign-in state, the Codex ChatGPT login, the provider key relay, and on Linux the Landlock level. There is a captured example on the install page.

skep onboard --check
skep onboard --check
# cut here: the skep doctor sections
Onboard checks:
- baseline: ready - builder locked, sha256 01db10ac4fc3
- policy scopes: ready - 7/7 scopes — the baseline governs these
- sandbox: ready - rings live: floor, locked baseline, capability layer, sandbox (bubblewrap)
- workdir: ready - ~/workspace is writable
- model: ready - Mock provider is ready for local V1 verification.
- steps: ready - all five complete

Egress truth:
model: mock — no call leaves this machine
workers: pypi.org, files.pythonhosted.org, registry.npmjs.org, proxy.golang.org allowed by the baseline; every other host asks
telemetry: none
captured: the end of skep onboard --check after the scripted run above, 2026-11-18

First governed run

Run, review, approve

Three commands. The flag on the first one decides whether the worker is behind an OS sandbox.

The two execution modes
FlagOS sandboxWhat that means
--execution-mode sandbox yes The worker runs under bubblewrap, Seatbelt or podman. Writes are confined to the run's own worktree and results. If no backend can be applied, the run does not start. Claude Code, Codex, Aider and pi always run this way.
--execution-mode workspace no No OS wall around the worker. It still works in a disposable worktree, its actions still pass skep's capability layer, and re-verification and approval still apply. Only skep's own worker can run this way.
the shortest path
$ skep run ~/workspace "fix the failing test" --execution-mode sandbox
# evidence, re-verification, the diff
$ skep review <task_id>
# applies the patch on skep/<task_id>
$ skep review <task_id> --approve
  • The run needs the model from step ①. With no model configured, skep's own worker falls back to a fixed routine that handles one Python hello-world task and fails anything else.
  • After the worker finishes, skep re-runs the verify command itself on a clean checkout. The outcome is passed, failed, unavailable or not_applicable; the run is printed [confirmed] only when the worker also reported passed.
  • Approving applies the patch on a new branch, skep/<task_id>. Your default branch does not move: review, merge or delete that branch as you would any other.
  • From the chat that onboarding opened, a plain message asking for the work does the same thing: the assistant proposes the run on a card and you confirm it.
pin a verify command
$ skep project setup ~/workspace --verify-command "uv run pytest"
a sandbox-mode run, then its approval
skep run ~/workspace "create a python hello world script" --execution-mode sandbox
dispatching task against ~/workspace
  → worker started (vcoding-minimal-0.1.0)  project: workspace (trusted_local_dev/build)  dispatch: allow dispatch.allow.run_request_resolved  landing: require_approval landing.require_approval.project_policy_disabled_auto_apply
  → plan: create hello.py
  → run: …/bin/python hello.py  policy: allow capability.allow.shell_verify (…/bin/python hello.py)
  → exit 0: …/bin/python hello.py  policy: allow capability.allow.shell_verify (…/bin/python hello.py)
  → verification: passed
  → terminal: completed
  → re-verify: passed [confirmed]  worker passed  re-ran clean: all exit 0 [command from the worker's own verify step]  re-ran …/bin/python hello.py  -> exit 0
task 01a1f130-6433-71f7-80b5-c4c122f6022d
  state:        completed (1.6s)
  verification: confirmed by re-verify (G10) — re-ran …/bin/python hello.py → exit 0
  worker claim: passed — created hello.py and verified it runs.
  evidence:     ~/.skep/supervisor/audit/01a1f130-6433-71f7-80b5-c4c122f6022d
  next:         skep review 01a1f130-6433-71f7-80b5-c4c122f6022d
skep review 01a1f130-6433-71f7-80b5-c4c122f6022d --approve
approved: task 01a1f130-6433-71f7-80b5-c4c122f6022d (by you)
  patch applied on branch skep/01a1f130-6433-71f7-80b5-c4c122f6022d in ~/workspace
  next: git -C ~/workspace switch skep/01a1f130-6433-71f7-80b5-c4c122f6022d
captured: skep run and skep review --approve, sandbox mode on bubblewrap, no model configured (the fallback worker), throwaway HOME shown as ~, 2026-11-18; the summary's verification and worker-claim lines in the format skep prints since v127

Your own agent

Hand the task to Claude Code or Codex

An external agent needs two things the built-in worker does not: its sign-in in the environment, and a pinned verify command.

Claude Code as the engine
# the token is printed by: claude setup-token
$ export CLAUDE_CODE_OAUTH_TOKEN=...
$ skep project setup ~/workspace --engine claude_code --verify-command "uv run pytest"
$ skep run ~/workspace "fix the failing test" --execution-mode sandbox

All five engines and how each signs in

  • The sandbox hides the keychain and the agent's login files, so Claude Code signs in from CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY, and Codex from OPENAI_API_KEY or an opt-in ChatGPT-plan login. Without one the run is refused with NO AUTH ENV.
  • A project run of an external agent is refused until the project pins a verify command. A --minimal run skips project policy, and that check with it.
  • The work directory from step ② is already a project. For any other repository, add --strategy trusted_local_dev the first time: a repository that is not a project yet is refused with project setup requires a pack or strategy.

Storage

Where skep keeps things

Everything is under one home directory: ~/.skep, unless SKEP_HOME names another. Secrets are files with owner-only permissions, never rows in the database.

Files under the skep home
PathWhat it holds
supervisor/supervisor.sqlite3Runs, events, approvals, projects and settings. No secret values.
supervisor/llm-secret, llm-secret-<id>Model provider keys saved from the web Settings page or skep provider set-key. Mode 0600.
supervisor/serve-tokenThe access token skep serve prints at startup. Mode 0600.
supervisor/*-secretMessenger channel secrets. Mode 0600.
serve.envOptional, written by you: KEY=VALUE lines the daemon loads at startup, such as an agent's sign-in token.
supervisor/audit/Evidence for every run, and the policy decision log (audit/policy/decisions.jsonl).
profile.json, first_run.jsonThe profile and the onboarding record. A key given as --api-key-env is stored as the variable's name.

A worker receives environment variables only by name, from an allowlist. Inside the sandbox serve.env, the serve token, the *-secret files, the audit directory, your SSH and cloud credentials and your shell history are hidden from the worker. The store stays readable, and so does the provider key skep's own worker needs when the key relay is off; the full list is in the sandboxing doc.