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.
$ 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.
| Step | What it asks | What 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 --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
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, reasonno_baseline. The floor still denies first: a worker'sgit pushis refused whatever you answer. -
A template is a starting set of rules.
skep policy explain builderprints 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 runskep policy approve --reapprove, which shows the difference first. -
Without the guided run,
skep policy approve --template builderlocks a baseline on its own. -
If you answered
noneat the sandbox step, the baseline is locked with every allowed write turned into a question.
# 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
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 # 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
First governed run
Run, review, approve
Three commands. The flag on the first one decides whether the worker is behind an OS sandbox.
| Flag | OS sandbox | What 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. |
$ 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,unavailableornot_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.
$ skep project setup ~/workspace --verify-command "uv run pytest" 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
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.
# 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 - The sandbox hides the keychain and the agent's login files, so Claude Code signs in from
CLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEY, and Codex fromOPENAI_API_KEYor an opt-in ChatGPT-plan login. Without one the run is refused withNO AUTH ENV. - A project run of an external agent is refused until the project pins a verify command. A
--minimalrun 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_devthe first time: a repository that is not a project yet is refused withproject 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.
| Path | What it holds |
|---|---|
supervisor/supervisor.sqlite3 | Runs, 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-token | The access token skep serve prints at startup. Mode 0600. |
supervisor/*-secret | Messenger channel secrets. Mode 0600. |
serve.env | Optional, 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.json | The 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.