Skip to main content

​
Quickstart

Get Spacebot running locally in under 5 minutes.

​
Docker (fastest)

1

Pull and run the container

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

Add your API key (optional)

You can pass API keys as environment variables to skip the onboarding flow:
docker run -d \
  --name spacebot \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -v spacebot-data:/data \
  -p 19898:19898 \
  ghcr.io/spacedriveapp/spacebot:latest
3

Send your first message

Open http://localhost:19898 in your browser. The web UI provides a chat interface to interact with your agent.You can also connect Spacebot to Discord, Slack, or Telegram. See the Docker deployment guide for messaging platform setup.
See Docker deployment for image variants, compose files, and configuration options.

​
Updating Docker Installs

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.

​
Build from Source

1

Install 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
2

Clone and build

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

Configure your API key

Spacebot needs at least one LLM provider key. Choose one of three options:

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

​
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"
4

Start Spacebot

# Background daemon (default)
spacebot

# Foreground with debug logging (recommended for first run)
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
5

Send your first message

The web UI is available at http://localhost:19898.If you configured a messaging platform (Discord, Slack, Telegram), you can also message your agent there.

​
Daemon Management

spacebot status    # show pid and uptime
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/):
FilePurpose
SOUL.mdPersonality, values, communication style
IDENTITY.mdName, nature, purpose
USER.mdInfo about the human the agent talks to
Template files are created on first run. Edit them to shape the agent’s personality. Changes are hot-reloaded (no restart needed).
Identity files are loaded into system prompts. They are NOT graph memories. For structured knowledge, use the memory system or drop files into the ingest/ folder.

​
Web UI

When the API is enabled (default), the web dashboard is served at: 
http://localhost:19898
The UI provides:
  • Chat interface for direct interaction
  • Memory browser to explore the knowledge graph
  • Agent topology visualization
  • Settings for provider keys, model routing, and permissions
  • Update management with one-click Docker updates

​
Development Mode

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

PlatformStatusSetup guide
DiscordSupportedDiscord setup
SlackSupportedSlack setup
TelegramSupportedTelegram setup
WebhookSupportedConfig reference
No messaging adapters are required. Without them, Spacebot is accessible via the web UI and HTTP API.

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

​
Authentication with Claude

Spacebot supports Anthropic OAuth as an alternative to static API keys. Use your Claude Pro, Max, or API Console subscription directly: 
spacebot auth login             # OAuth via Claude Pro/Max (opens browser)
spacebot auth login --console   # OAuth via API Console
spacebot auth status            # show credential status and expiry
spacebot auth refresh           # manually refresh the access token
spacebot auth logout            # remove stored credentials
OAuth tokens are stored in anthropic_oauth.json and auto-refresh transparently before each API call. When OAuth credentials are present, they take priority over a static ANTHROPIC_API_KEY.

​
Next Steps

Docker Deployment

Run Spacebot in a container with slim or full image variants

Configuration

Full config.toml reference with all available options

Model Routing

Configure multi-tier model routing with fallback chains

Memory System

Structured knowledge graph with typed memories and associations

Multi-Agent Setup

Run multiple agents with isolated workspaces and identities

Cron Jobs

Schedule recurring tasks with natural language or cron expressions

Build docs developers (and LLMs) love

Get started for freeTalk to us