Docker

The Docker image packages the gateway and CLI into a single container using Bun as the runtime.

Quick start

Build the image

docker build -t spaceduck .

Run the container

docker run -d \
  -p 3000:3000 \
  -v spaceduck-data:/data \
  spaceduck

Open http://localhost:3000 to launch the Settings UI and configure your AI provider.

Docker Compose

A docker-compose.yml is included for the common case.

# Start
docker compose up --build -d

# View logs
docker compose logs -f

# Stop
docker compose down

Data persists in the spaceduck-data volume across restarts and upgrades.

Persistence

The container stores its SQLite database at /data/spaceduck.db. The compose file mounts a named volume at /data, so your data survives container restarts. Default database path inside the container:

/data/spaceduck.db

Environment variables

Variable	Default	Purpose
`PORT`	`3000`	Gateway listen port
`LOG_LEVEL`	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`)
`PROVIDER_NAME`	(unset)	AI provider (configured via Settings UI or env)
`PROVIDER_MODEL`	(unset)	Optional model override
`MEMORY_BACKEND`	`sqlite`	Memory backend
`MEMORY_CONNECTION_STRING`	`spaceduck.db`	SQLite file path (set to `/data/spaceduck.db` in Docker)

API keys

Pass provider API keys as environment variables:

GEMINI_API_KEY
OPENROUTER_API_KEY
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION

Use a local .env file with Docker Compose and keep it out of version control.

Running the CLI inside the container

The image includes the CLI bundle. If your container is named spaceduck:

docker exec -it spaceduck bun /app/apps/cli/src/index.ts status
docker exec -it spaceduck bun /app/apps/cli/src/index.ts version
docker exec -it spaceduck bun /app/apps/cli/src/index.ts config paths

Local AI providers

If you want Spaceduck inside Docker to connect to a model server running on your host machine (LM Studio, llama.cpp, etc.):

macOS / Windows
Linux

Docker Desktop provides host.docker.internal to reach the host:

docker run -d \
  -p 3000:3000 \
  -v spaceduck-data:/data \
  -e PROVIDER_NAME=llamacpp \
  -e PROVIDER_BASE_URL=http://host.docker.internal:8080/v1 \
  spaceduck

host.docker.internal may not exist by default. Options:Host networking (simplest for local dev):

docker run -d \
  --network=host \
  -v spaceduck-data:/data \
  -e PORT=3000 \
  -e PROVIDER_NAME=llamacpp \
  -e PROVIDER_BASE_URL=http://127.0.0.1:8080/v1 \
  spaceduck

Explicit host mapping:

docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -p 3000:3000 \
  -v spaceduck-data:/data \
  -e PROVIDER_NAME=llamacpp \
  -e PROVIDER_BASE_URL=http://host.docker.internal:8080/v1 \
  spaceduck

Healthcheck

The image includes a built-in healthcheck against /api/health. Verify manually:

curl http://localhost:3000/api/health

Notes

Playwright/browser tooling is not included in the default image to keep it lean.
The Docker image is intended for gateway-first usage. The CLI is included for setup and maintenance inside the container.
To add custom binaries or system packages, extend the image with your own Dockerfile.

Start Here

Install

Model Providers

Platforms

Tools

Concepts

Reference

Quick start

Docker Compose

Persistence

Environment variables

API keys

Running the CLI inside the container

Local AI providers

Healthcheck

Notes

​Quick start

​Docker Compose

​Persistence

​Environment variables

​API keys

​Running the CLI inside the container

​Local AI providers

​Healthcheck

​Notes

Quick start

Docker Compose

Persistence

Environment variables

API keys

Running the CLI inside the container

Local AI providers

Healthcheck

Notes