local

Manage a local Sibyl instance (Docker-based). local runs the full Sibyl stack (API, worker, web UI, and SurrealDB) in Docker with batteries included: first run prompts for API keys, generates secrets, writes a compose file under ~/.sibyl/local, and opens the web UI.

The top-level sibyl up and sibyl down commands are aliases of local start and local stop. For a pinned, production-leaning stack with explicit image tags, use sibyl docker instead.

Commands

Command	Description
sibyl local start	Start the local instance (alias: sibyl up)
sibyl local stop	Stop the local instance (alias: sibyl down)
sibyl local upgrade	Move a running instance to new server images
sibyl local status	Show status of local services
sibyl local logs	Show logs from local services
sibyl local reset	Reset the instance (removes all data)
sibyl local setup	Set up Claude/Codex integration

---

local start

Start the local instance. On first run, prompts for API keys and generates secrets; later runs reuse saved configuration. Also available as sibyl up.

sibyl local start [options]
sibyl up [options]

Option	Default	Description
--no-browser	false	Don't open the browser after starting
--pull	false	Pull latest images before starting

Examples

# Start and open the web UI
sibyl up

# Start headless and pull fresh images
sibyl up --no-browser --pull

---

local stop

Stop the local instance. Also available as sibyl down.

sibyl local stop [options]
sibyl down [options]

Option	Default	Description
--destroy	false	Also remove volumes (deletes all data)

---

local upgrade

Move a running local instance to new server images without leaving it down. The images for the target tag are pulled while the current containers keep serving, so a failed pull changes nothing. Only then are the pins moved and the services recreated. SurrealDB follows the same rule as sibyl docker upgrade: a CLI-written default moves up to this release's server, and a newer or hand-written image stays.

There is no rollback once the new services start. The new SurrealDB may already have opened the data, and an older API must not run against a schema a newer one migrated. If the services fail to start or do not report healthy within two minutes, the command keeps the new pins, says so, and points at sibyl local logs; a slow migration may still finish, which sibyl local status shows. Re-running the same sibyl local upgrade --tag <tag> retries the start. When nothing is left running, it says to start it with SIBYL_IMAGE_TAG=<tag> sibyl up instead, which keeps the SurrealDB image the pins name.

Without --tag the target is this CLI's image, and the command refuses with nothing changed when the instance already runs, or pins, a newer release than that, since the API must not move backwards onto a schema a newer one migrated. Pass --tag to choose an older version deliberately.

A stopped instance is not started. The command stops with nothing changed when Docker cannot report the state, when the current tag cannot be read, or when another sibyl local upgrade is already running. Containers are matched on the compose file that created them, not the project name, so another project in a directory called local does not count. When the running Sibyl belongs to the sibyl docker runtime, it says so and names sibyl docker upgrade instead.

sibyl local upgrade [options]

Option	Default	Description
--tag	this CLI's image	Server image tag to move to; required to move backwards

sibyl update runs this for a running local instance after it upgrades the CLI.

---

local status

Show the status of local Sibyl services.

sibyl local status

---

local logs

Show logs from local Sibyl services. Pass a service name to scope the output.

sibyl local logs [service] [options]

Argument	Required	Description
service	No	Service name (api, web, worker, surrealdb)

Option	Short	Default	Description
--follow	-f	on	Follow log output
--tail		100	Number of lines to show

---

local reset

Reset the local instance: stop containers, delete all data, and remove saved configuration. Prompts for confirmation unless --force is given.

sibyl local reset [options]

Option	Short	Default	Description
--force	-f	false	Skip confirmation

---

local setup

Set up Claude/Codex integration: skills for Claude Code and Codex, plus Claude Code hooks (session-start and prompt injection). In development mode it symlinks; in package mode it copies.

sibyl local setup [options]

Option	Short	Default	Description
--status	-s	false	Only show current installation status
--snippet		false	Show the prompt snippet for Claude/Codex config

Notes

• Services bind to 127.0.0.1: web UI on 3337, API on 3334, SurrealDB on 8000.
• First-run setup reads OPENAI_API_KEY and ANTHROPIC_API_KEY from the environment when present; otherwise configure keys from the web UI.
• local reset and local stop --destroy delete the SurrealDB volume and all data; use them deliberately.

Related Commands

• sibyl docker - Pinned, production-leaning Docker stack
• sibyl service - Native host daemon service files
• sibyl doctor - Verify health after starting
• sibyl skill - Install the skill stub without hooks