Setup Wizard

4 min readFor first-time operatorsUpdated 2026-05-19

What you'll do

Run craik setup once to initialize the local Craik home, the local SQLite store, and a default gateway configuration. By the end you'll have inspectable, non-secret configuration on disk and a clear path to adding identity, credentials, and gateway access.

The minimal setup

One command to get a workable Craik home

craik setup

This:

• Resolves CRAIK_HOME (or ~/.craik/ by default).
• Creates the per-data-class subdirectories Craik writes to.
• Persists a default craik.gateway_config payload.
• Prints the resolved paths and next-step guidance.

craik setup is secrets-free

The wizard writes inspectable, non-secret configuration only. It does not ask for API keys, channel tokens, webhook secrets, or bearer credentials. The secrets_written field in the output is always false.

Store secret material in your operator's secret manager or in environment variables that the specific adapter consumes — Craik references them by name, never copies them into config.

What gets written

$CRAIK_HOME/
  config/
    craik.toml          # user-level CLI defaults
    gateway.json        # persisted craik.gateway_config payload
  state/
    craik.sqlite        # the local store
  secrets/              # empty — operator-managed
  receipts/  handoffs/  case-files/  projects/  logs/  cache/

Everything in config/ is safe to read, diff, and version. Nothing in config/ references a secret by value; secret references are by name only.

Add identity and a credential profile

craik setup stops short of identity and credentials on purpose — those deserve a deliberate decision. Once setup completes:

Log in as an OIDC operator

craik login

Add a credential profile that points at an env var

craik auth add anthropic:work \
  --kind=api-key \
  --env-var=ANTHROPIC_API_KEY
craik auth status

The full credential surface — local-CLI OAuth, secret-manager references, Stigmem-backed credential references, workload identity, RFC 8693 token exchange, approval-gated first use — lives in Authentication and credentials.

Enable the gateway

Craik ships a foreground gateway daemon mode for local health checks, webhook validation, scheduled automation helpers, and fixture messaging ingress under one governed boundary. Wire it in during setup or any time after:

Persist the gateway config with a policy envelope

craik setup --enable-gateway --policy-envelope-id policy_gateway

For a public bind, the gateway requires an explicit policy envelope and an explicit insecure-public override. Craik refuses to expose itself to a non-loopback host without a policy envelope, and it fails closed unless the operator acknowledges that TLS termination is being handled outside Craik:

Public bind with explicit policy

craik setup \
  --gateway-bind-host 0.0.0.0 \
  --policy-envelope-id policy_gateway \
  --allow-insecure-public-gateway

The setup output prints:

Resolved paths

CRAIK_HOME, state, config, and gateway file locations.

gateway_config

The persisted payload — including the bound policy envelope id, channel allowlists, and ingress paths.

gateway_runtime_state

The initial stopped lifecycle state written alongside the gateway configuration.

secrets_written = false

Always. Confirmation that the wizard hasn't asked for or stored secret material.

Next steps

Recommended commands: craik doctor for diagnostics, gateway review pointers, and the right docs to read before enabling channel ingress.

Run diagnostics before going live

Don't start an always-on gateway without running craik doctor first:

Health-check identity, credentials, and provider posture

craik doctor

Diagnostics surface unreachable credential profiles, expired tokens, bad policy bindings, and missing gateway dependencies — every one of which is better caught at the operator's terminal than at the gateway's first inbound request.

Reset and re-run

craik setup is idempotent. Re-running it doesn't blow away project registrations or receipts — it re-resolves paths and updates the gateway config when flags change. First-time setup can initialize a new home without authentication; reconfiguring an existing local store requires an active operator session.

To start from a clean slate:

Start over completely

rm -rf "$CRAIK_HOME"
craik setup

What's next

Do nextAuthentication & credentialsOIDC login, credential profiles, pools, workload identity, and approval flow.DiagnoseRun doctorHealth-check the whole identity / credential / provider chain before live calls.ReferenceGateway daemon modeThe full gateway contract, channels, and ingress policy options.