Docker

Run Spacebot in a container with the unified Spacebot image.

Quick Start

docker run -d \
  --name spacebot \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -v spacebot-data:/data \
  -p 19898:19898 \
  ghcr.io/spacedriveapp/spacebot:latest

The web UI is available at http://localhost:19898.

Image Behavior

There is one published image: ghcr.io/spacedriveapp/spacebot.

• latest tracks the rolling release
• vX.Y.Z pins a specific release
• Browser support is built in: Chromium is downloaded on first browser-tool use and cached under /data
• Legacy -slim / -full tags are deprecated

Data Volume

All persistent data lives at /data inside the container. Mount a volume here.

/data/
├── config.toml              # optional, can use env vars instead
├── embedding_cache/         # FastEmbed model cache (~100MB, downloaded on first run)
├── agents/
│   └── main/
│       ├── SOUL.md          # agent personality and voice
│       ├── IDENTITY.md      # agent purpose and scope
│       ├── ROLE.md          # agent responsibilities
│       ├── workspace/       # working directory (sandbox boundary)
│       ├── data/            # SQLite, LanceDB, redb databases
│       └── archives/        # compaction transcripts
└── logs/                    # log files (daily rotation)

On first launch with no config, Spacebot creates a default main agent with template identity files. The FastEmbed model (~100MB) downloads on first memory operation -- subsequent starts use the cache.

Configuration

Environment Variables

The simplest approach. No config file needed.

docker run -d \
  --name spacebot \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e DISCORD_BOT_TOKEN="..." \
  -v spacebot-data:/data \
  -p 19898:19898 \
  ghcr.io/spacedriveapp/spacebot:latest

Available environment variables:

Config File

Mount a config file into the volume for full control:

docker run -d \
  --name spacebot \
  -v spacebot-data:/data \
  -v ./config.toml:/data/config.toml:ro \
  -p 19898:19898 \
  ghcr.io/spacedriveapp/spacebot:latest

Config values can reference environment variables with env:VAR_NAME:

[llm]
anthropic_key = "env:ANTHROPIC_API_KEY"

See Configuration for the full config reference.

Docker Compose

services:
  spacebot:
    image: ghcr.io/spacedriveapp/spacebot:latest
    container_name: spacebot
    restart: unless-stopped
    ports:
      - "19898:19898"
    volumes:
      - spacebot-data:/data
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # Optional:
      # - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}

volumes:
  spacebot-data:

Browser Workers

No alternate image is needed. The browser tool downloads Chromium on demand and caches it on the mounted /data volume.

Building the Image

From the spacebot repo root:

docker build -t spacebot:local .

The multi-stage Dockerfile has two stages:

1. Builder stage -- Rust toolchain + Bun. Compiles the React frontend, then builds the Rust binary with the frontend embedded.
2. Runtime stage -- Minimal Debian runtime with Chrome's shared-library dependencies. The browser binary itself is fetched on demand.

Build time is ~5-10 minutes on first build (downloading and compiling Rust dependencies). Subsequent builds use the cargo cache.

Ports

The API server binds to 0.0.0.0 inside the container (overriding the default 127.0.0.1 bind). The webhook port is only needed if you enable the webhook messaging adapter.

Health Check

The API server responds to GET /api/health. Use this for container health checks:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:19898/api/health"]
  interval: 30s
  timeout: 5s
  retries: 3

Container Behavior

• Spacebot runs in foreground mode (--foreground) inside the container. No daemonization.
• Logs go to stdout/stderr. Use docker logs to view them.
• Graceful shutdown on SIGTERM (what docker stop sends). Drains active channels, closes database connections.
• The PID file and Unix socket (used in daemon mode) are not created.

Updates

Spacebot checks for new releases on startup and every hour. When a new version is available, a banner appears in the web UI.

You can also open Settings → Updates for update status, one-click apply controls (Docker), and manual command snippets.

latest is supported and continues to receive updates. Use explicit version tags only when you want controlled rollouts.

Manual Update

docker compose pull spacebot
docker compose up -d --force-recreate spacebot

If you're not using Compose:

docker pull ghcr.io/spacedriveapp/spacebot:latest
docker stop spacebot && docker rm spacebot
# re-run your original docker run command with the new image tag

One-Click Update

Mount the Docker socket to enable updating directly from the web UI:

services:
  spacebot:
    image: ghcr.io/spacedriveapp/spacebot:latest
    container_name: spacebot
    restart: unless-stopped
    ports:
      - "19898:19898"
    volumes:
      - spacebot-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

When the socket is mounted, the update banner shows an Update now button that pulls the new image and recreates the container automatically. Your /data volume is preserved across updates.

Without the socket mount, the banner still notifies you of new versions but you'll need to update manually.

One-click updates are intended for containers running Spacebot release tags. If you're running a custom/self-built image, update by rebuilding your image and recreating the container.

Native / Source Builds

If Spacebot is installed from source (cargo install --path . or a local release build), updates are manual:

1. Pull latest source
2. Rebuild/reinstall the binary
3. Restart Spacebot

The web UI still shows update availability, but it cannot rebuild binaries for native installs.

Update API

You can also check for and trigger updates programmatically:

# Check for updates
curl http://localhost:19898/api/update/check

# Force a fresh check
curl -X POST http://localhost:19898/api/update/check

# Apply update (requires Docker socket)
curl -X POST http://localhost:19898/api/update/apply

CI / Releases

Images are built and pushed to ghcr.io/spacedriveapp/spacebot via GitHub Actions (.github/workflows/release.yml).

Triggers:

• Push a v* tag (e.g. git tag v0.1.0 && git push --tags)
• Manual dispatch from the Actions tab

Tags pushed per release:

# Manual single-instance deploy
fly launch --image ghcr.io/spacedriveapp/spacebot:latest
fly volumes create spacebot_data --size 5
fly secrets set ANTHROPIC_API_KEY="sk-ant-..."
fly deploy