docker

Manage a self-hosted Sibyl Docker deployment. docker generates a pinned compose stack under ~/.sibyl/docker, starts and stops it, tails its logs, and upgrades it to new image tags. It is the production-leaning path: explicit image tags, generated secrets, and optional worker and crawler services.

For the simpler, batteries-included local instance, use sibyl local (and its sibyl up / sibyl down aliases) instead.

Commands

Command	Description
sibyl docker init	Generate pinned compose files under ~/.sibyl/docker
sibyl docker up	Start the Docker deployment
sibyl docker logs	Show Docker deployment logs
sibyl docker down	Stop the Docker deployment
sibyl docker upgrade	Pull current images and recreate containers

---

docker init

Generate pinned compose and env files under ~/.sibyl/docker and create a matching context.

sibyl docker init [options]

Option	Short	Default	Description
--api-port		3334	Host API port
--web-port		3337	Host web port
--surreal-port		8000	Host SurrealDB port
--tag		(CLI version)	Sibyl image tag
--with-worker		false	Add Valkey and a worker service
--with-crawler		false	Use the crawler-enabled API image
--context		docker	Context name to create
--activate / --no-activate		on	Set the created context active
--force	-f	false	Overwrite existing files

Examples

# Generate the default stack and activate its context
sibyl docker init

# Pin a tag and add the worker + crawler services
sibyl docker init --tag 1.4.10 --with-worker --with-crawler

# Regenerate over an existing install
sibyl docker init --force

---

docker up

Start the deployment. Requires an initialized runtime and a working Docker install.

sibyl docker up [options]

Option	Default	Description
--pull	false	Pull images before starting

---

docker logs

Show deployment logs. Pass a service name to scope the output.

sibyl docker logs [service] [options]

Argument	Required	Description
service	No	Optional service name

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

---

docker down

Stop the deployment.

sibyl docker down [options]

Option	Short	Default	Description
--volumes	-v	false	Also remove volumes

---

docker upgrade

Move the deployment to new images: pull them, then write the new pins and recreate the containers. With --tag it moves the Sibyl images to that tag; without it, it re-pulls the current pins.

Upgrade also moves the SurrealDB image up to the server this CLI release runs (v3.2.4), so upgrade the CLI before you upgrade the deployment. It pulls every new image before it touches the compose file, so a failed pull exits non-zero and leaves the deployment and its pins as they were. Compose then recreates SurrealDB and waits for it to report healthy before it starts the new API. If that start fails, upgrade exits non-zero with the new pins kept, because SurrealDB may already have opened the data on the new version; start it again with sibyl docker up. A SIBYL_SURREAL_IMAGE set in ~/.sibyl/docker/.env or the shell still wins, and a SurrealDB image you wrote by hand, or one newer than the CLI's, stays as it is. Upgrade warns in both cases.

sibyl docker upgrade [options]

Option	Default	Description
--tag	(none)	Sibyl image tag to move to

Example

sibyl docker upgrade --tag 1.4.10

Notes

• Ports bind to 127.0.0.1 only. The API is published on the API port, the web UI on the web port, and SurrealDB on the SurrealDB port.
• init generates a SurrealDB password and JWT secret into a 0600 env file; keep that file safe.
• The worker service requires Valkey, which --with-worker adds and wires up automatically.
• Most subcommands refuse to run until you have run docker init.

Related Commands

• sibyl local - Simpler local Docker instance with sibyl up/down
• sibyl service - Run a native host daemon instead of Docker
• sibyl update - Upgrade a running deployment in step with the CLI