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

​
Quick start

1

Build the image

docker build -t spaceduck .
2

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

VariableDefaultPurpose
PORT3000Gateway listen port
LOG_LEVELinfoLogging verbosity (debug, info, warn, error)
PROVIDER_NAME(unset)AI provider (configured via Settings UI or env)
PROVIDER_MODEL(unset)Optional model override
MEMORY_BACKENDsqliteMemory backend
MEMORY_CONNECTION_STRINGspaceduck.dbSQLite 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.):
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

​
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.