Documentation menu
On this page

Onboarding: skep onboard

pipx install skep && skep onboard

skep onboard takes a new machine from nothing to a governed chat in five steps. Plain prompts, no full-screen UI, so it works over SSH and inside another tool's terminal. Every step writes a record under ~/.skep, so running it again picks up at the first step that is not done yet.

A fresh install asks for everything (ask, reason no_baseline) until a baseline is approved; a home from an earlier skep keeps deciding as before, and skep doctor says how to approve one.

Step What it asks What it writes
① model provider, model, endpoint, and the name of the env var that holds the API key (never the key itself). With no provider named it first tests the provider already configured and keeps it when it works; only then does it look for a local Ollama. A switch makes one test call and rolls back to the previous provider if that call fails, and prints where prompts go (LOCAL … nothing leaves this machine or CLOUD … leaves this machine for <host>) the provider registry, the assistant settings, profile.json
② work directory a path (default ~/workspace), created if missing a project, with the verify_command inferred from the repo
③ sandbox auto (the native backend: Seatbelt on macOS, bubblewrap on Linux), podman, or none. Docker is detected but not offered, because skep has no docker backend the sandbox_backend setting
④ template builder (the default), operator or assistant, shown as their skep policy explain tables. assistant cannot edit code the locked baseline, after you type yes
work without asking once, in plain words: may skep work in the work directory without asking? Inside the sandbox it then 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. Enter means no. Not offered with no sandbox or no pinned test command, and it says why unlocked on that one project (ADR 0061); the answer in onboard.json
⑤ role one of the same three names ~/.skep/first_run.json

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

none is a real answer

If the host has no usable sandbox, say none. The output then lists the protections that are still active: the floor, the locked baseline and the capability layer. Nothing confines the worker process, so the baseline is locked with every allowed write turned into an ask. Under builder, a worker asks before every write instead of writing freely inside the workspace. You see the changed rules before you type yes.

Scripts and docs

Every prompt has a flag, with the same names skep setup uses:

skep onboard --provider ollama --model qwen3:14b --workdir ~/code/app \
  --sandbox auto --template builder --role builder --yes --no-chat

--yes accepts the default for any step you did not pass a flag for and skips the typed yes. It never turns on working without asking; pass --unlocked for that. --provider takes mock, ollama, openai-compatible, or a preset id from skep provider presets. A flag that differs from a step you already finished runs that step again. For example, --template operator re-locks the baseline and shows the diff first. Changing the sandbox after the baseline is locked (--sandbox none after auto, or back) re-opens step ④ too. The locked baseline must match what that template locks under the new sandbox, so you approve the new candidate before it is locked.

skep onboard --check

This is skep doctor plus the onboarding checks. It also checks that:

  • the baseline still matches its lock (a hand edit is reported as baseline_tampered)
  • the locked baseline is what step ④ locks for your template under the current sandbox (a sandbox change since the lock means you re-run skep onboard)
  • engine v2 is on for every scope (a fresh home is seeded that way)
  • the chosen sandbox backend is present
  • the work directory is writable
  • the model is reachable
  • all five steps are done

It ends with the egress-truth block, which says where model prompts go, which hosts the baseline lets workers reach, and ends with telemetry: none. It exits 0 only when every check is ready.

The first session: why under every verdict

While ~/.skep/first_run.json is active (onboard step ⑤ starts it), every verdict card in skep chat and the web chat carries one more line, why:, naming the rule and layer that decided it, for example why: allowed: rule r1 in the learned layer — capability.allow.learned_rule. A card with no rule behind it says it asked by default. Each turn ends with a tally:

skep: 6 allowed · 1 asked · 0 denied — skep policy why for any of them

After 10 turns or 25 verdicts the chat offers once to turn this down. skep onboard --quiet turns it off, skep onboard --verbose brings it back (the web offer's "Turn it down" button calls POST /api/onboard/transparency). A home that never ran skep onboard has no first_run.json and shows none of it. The model cannot flip this switch; only you can.

In the browser

The /setup page has a "First run (skep onboard)" card with the same five steps. It calls the same functions through GET /api/onboard and POST /api/onboard/<step>, so a step finished in the browser is finished in the terminal too.