Quickstart

Get Spacebot running locally in under 5 minutes.

Docker (fastest)

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

The web UI is available at http://localhost:19898. On first launch with no API keys configured, the UI will prompt you to add a provider key in Settings. You can also pass keys as environment variables:

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

See Docker deployment for image variants, compose files, and configuration options.

To update Docker installs, pull and recreate the container:

docker pull ghcr.io/spacedriveapp/spacebot:latest
docker stop spacebot && docker rm spacebot
# re-run your docker run command

If you mount /var/run/docker.sock, the web UI can apply Docker updates directly from the update banner. You can also manage updates from Settings → Updates in the web UI.

Build from source

Prerequisites

• Rust 1.85+ — rustup update stable
• Bun (optional, for the web UI) — curl -fsSL https://bun.sh/install | bash
• An LLM API key — Anthropic, OpenAI, OpenRouter, Kilo Gateway, or OpenCode Go

Install

git clone https://github.com/spacedriveapp/spacebot.git
cd spacebot

# Optional: build the web UI (React + Vite, embedded into the binary)
cd interface && bun install && cd ..

# Install the binary
cargo install --path .

The build.rs script automatically runs bun run build during compilation if interface/node_modules exists. Without it, the binary still works — you just get an empty UI on the web dashboard.

Configure

Spacebot needs at least one LLM provider key. You can either set an environment variable or create a config file.

Option A: Environment variable (fastest)

export ANTHROPIC_API_KEY="sk-ant-..."

This is enough. Spacebot will create a default main agent with sensible defaults and no messaging adapters. The web UI and HTTP API will be available on http://localhost:19898.

Option B: Interactive onboarding

Just run spacebot with no config file and no API key env var set. It will walk you through provider selection, API key entry, agent naming, and optional Discord setup.

Option C: Config file

Create ~/.spacebot/config.toml:

[llm]
anthropic_key = "sk-ant-..."
# or: openrouter_key = "sk-or-..."
# or: kilo_key = "sk-..."
# or: opencode_go_key = "..."
# or: openai_key = "sk-..."
# Keys also support env references: anthropic_key = "env:ANTHROPIC_API_KEY"

[[agents]]
id = "main"

# Optional: connect to Discord
[messaging.discord]
enabled = true
token = "env:DISCORD_BOT_TOKEN"

# Route Discord messages to the main agent
[[bindings]]
agent_id = "main"
channel = "discord"

See Configuration for the full config reference.

Run

# Background daemon (default)
spacebot

# Foreground with debug logging (recommended for first run / development)
spacebot start -f -d

# During development with cargo
cargo run -- start -f -d

On first launch, Spacebot automatically creates:

• ~/.spacebot/ — instance directory
• ~/.spacebot/agents/main/data/ — SQLite, LanceDB, and redb databases
• ~/.spacebot/agents/main/workspace/ — identity files and ingest directory

Daemon management

spacebot status    # show pid and uptime
spacebot stop      # graceful shutdown
spacebot restart   # stop + start
spacebot restart -f -d  # restart in foreground with debug

Logs go to ~/.spacebot/agents/{id}/data/logs/ in daemon mode, or stderr in foreground mode.

Identity files

Each agent has three optional markdown files in its workspace (~/.spacebot/agents/{id}/workspace/):

Template files are created on first run. Edit them to shape the agent's personality. Changes are hot-reloaded (no restart needed).

Web UI

When the API is enabled (default), the web dashboard is served at:

http://localhost:19898

During development, the Vite dev server runs separately with API proxying:

cd interface && bun run dev
# UI at http://localhost:3000, proxies /api to http://localhost:19898

Messaging platforms

No messaging adapters are required. Without them, Spacebot is accessible via the web UI and HTTP API.

CLI flags reference

spacebot [OPTIONS] [COMMAND]

Commands:
  start     Start the daemon [default]
  stop      Stop the running daemon
  restart   Restart the daemon
  status    Show daemon status

Global options:
  -c, --config <PATH>    Path to config file
  -d, --debug            Enable debug logging

Start/restart options:
  -f, --foreground       Run in foreground instead of daemonizing

Next steps