Spacebot

https://docs.spacebot.sh/
Admin
Spacebot is an agentic AI system built in Rust that orchestrates specialized concurrent processes...
Tokens:76,349
Snippets:663
Trust Score:4.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Start Spacebot Development Server

Source: https://docs.spacebot.sh/quickstart

This command navigates to the `interface` directory and starts the Vite development server for the Spacebot Web UI. The UI will be accessible at `http://localhost:3000` and will proxy API requests to the Spacebot backend running on `http://localhost:19898`.

```bash
cd interface && bun run dev
```

--------------------------------

### Clone and Build Spacebot from Source

Source: https://docs.spacebot.sh/quickstart

Clones the Spacebot repository, navigates into the directory, and installs the binary using Cargo. This process requires Rust 1.85+.

```bash
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 ..

# Optional: build the OpenCode embed (live coding UI in the Workers tab)
# Requires Node 22+ (use fnm: fnm install v24.14.0 && fnm use v24.14.0)
./scripts/build-opencode-embed.sh

# Install the binary
cargo install --path .
```

--------------------------------

### Run Spacebot with Specific Configuration File

Source: https://docs.spacebot.sh/quickstart

This command illustrates how to start a Spacebot instance using a specific configuration file via the `-c` flag. The instance data directory is inferred from the parent directory of the provided config file. This is an alternative to setting the `SPACEBOT_DIR` environment variable.

```bash
cargo run -- -c ~/.spacebot/dev/config.toml start -f -d
```

--------------------------------

### Run Spacebot with Docker and API Key

Source: https://docs.spacebot.sh/quickstart

Starts Spacebot as a detached Docker container, including an environment variable for an LLM API key. This bypasses the need for interactive API key setup.

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

--------------------------------

### Configure Spacebot with TOML File

Source: https://docs.spacebot.sh/quickstart

Creates a TOML configuration file at `~/.spacebot/config.toml` to specify LLM API keys and agent settings, including optional Discord integration.

```toml
# ~/.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"
```

--------------------------------

### Update Spacebot Docker Installation

Source: https://docs.spacebot.sh/quickstart

Updates a Spacebot Docker installation by pulling the latest image, stopping and removing the existing container, and then re-running the container with the original command.

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

--------------------------------

### Run Production and Development Spacebot Instances

Source: https://docs.spacebot.sh/quickstart

These commands demonstrate how to run both the production and development instances of Spacebot concurrently. The production instance uses the default configuration, while the development instance is launched from source with a specified data directory (`SPACEBOT_DIR`) and runs in the foreground.

```bash
# Production (installed binary, default ~/.spacebot)
spacebot start

# Dev (from source, separate data directory)
SPACEBOT_DIR=~/.spacebot/dev cargo run -- start -f -d
```

--------------------------------

### Configure Development Instance Ports

Source: https://docs.spacebot.sh/quickstart

This TOML configuration file sets up the development instance of Spacebot. It specifies API and webhook ports, ensuring they do not conflict with a running production instance. It also includes a placeholder for the Anthropic API key.

```toml
[llm]
anthropic_key = "env:ANTHROPIC_API_KEY"

[[agents]]
id = "main"

# Use different ports so dev and prod don't conflict
[api]
port = 19899

[messaging.webhook]
port = 18790
```

--------------------------------

### Run Spacebot with Docker

Source: https://docs.spacebot.sh/quickstart

Starts Spacebot as a detached Docker container, mapping the data volume and exposing the web UI port. The web UI is accessible at http://localhost:19898.

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

--------------------------------

### Create Development Instance Directory

Source: https://docs.spacebot.sh/quickstart

This command creates a new directory for the development instance of Spacebot. It ensures that the parent directories exist if they don't already. This directory will house all data for the dev instance, keeping it separate from the production instance.

```bash
mkdir -p ~/.spacebot/dev
```

--------------------------------

### Interactive Session Setup with OpenCode Worker

Source: https://docs.spacebot.sh/opencode

Demonstrates how to initiate an interactive session with an OpenCode worker for tasks like project setup. The worker enters a 'WaitingForInput' state after the initial task, allowing for follow-up messages that preserve context.

```shell
spawn_worker: task="set up the project", worker_type: opencode, interactive: true, directory: /code/myapp
  → OpenCode creates a session, runs initial task
  → Worker enters WaitingForInput
route: worker_id=abc, message="now add the database layer"
  → Follow-up sent to the same OpenCode session
  → Context from the first task is preserved
```

--------------------------------

### Spacebot CLI Command Structure

Source: https://docs.spacebot.sh/quickstart

This shows the basic structure of the Spacebot command-line interface, including global options and available commands. It details options like `--config` for specifying a config file and `--debug` for enabling debug logging, as well as commands for managing the daemon.

```bash
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
```

--------------------------------

### Manage Spacebot Daemon

Source: https://docs.spacebot.sh/quickstart

Commands for managing the Spacebot daemon, including checking its status, stopping, restarting, and restarting in foreground debug mode.

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

--------------------------------

### Install All Skills from a Repository

Source: https://docs.spacebot.sh/skills

Installs all available skills from a specified GitHub repository using the spacebot CLI. This is useful for bulk installation of related skills.

```bash
spacebot skill add vercel-labs/agent-skills
```

--------------------------------

### TOML Configuration Reference

Source: https://docs.spacebot.sh/docker

Example of referencing environment variables within a TOML configuration file for Spacebot.

```toml
[llm]
anthropic_key = "env:ANTHROPIC_API_KEY"
```

--------------------------------

### Browser Configuration

Source: https://docs.spacebot.sh/browser

Configuration examples for the browser tool, including global defaults and per-agent overrides in TOML format.

```toml
[defaults.browser]
enabled = true
headless = true
evaluate_enabled = false
persist_session = false
close_policy = "close_browser"
executable_path = ""
screenshot_dir = ""

[[agents]]
id = "web-scraper"

[agents.browser]
evaluate_enabled = true
headless = false
persist_session = true
close_policy = "detach"
```

--------------------------------

### GET /agents/tools

Source: https://docs.spacebot.sh/sandbox

Retrieves a list of installed binaries available in the persistent tools directory for dashboard observability.

```APIDOC
## GET /agents/tools

### Description
This endpoint lists the binaries installed in the durable binary directory, providing their names, sizes, and last modified timestamps. This is useful for observing the available tools on the system.

### Method
GET

### Endpoint
/agents/tools

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **tools_bin** (string) - The path to the directory containing durable binaries.
- **binaries** (array) - A list of objects, where each object represents an installed binary.
  - **name** (string) - The name of the binary.
  - **size** (integer) - The size of the binary file in bytes.
  - **modified** (string) - The last modified timestamp of the binary in ISO 8601 format.

#### Response Example
```json
{
  "tools_bin": "/data/tools/bin",
  "binaries": [
    { "name": "gh", "size": 1234567, "modified": "2026-02-20T14:15:00Z" },
    { "name": "ripgrep", "size": 3456789, "modified": "2026-02-15T10:30:00Z" }
  ]
}
```
```

--------------------------------

### MiniJinja Template Syntax Examples

Source: https://docs.spacebot.sh/prompts

Illustrates the basic syntax for MiniJinja templates, including variable substitution, conditional logic, loops, and optional sections. These examples are representative of Jinja2 syntax.

```jinja
{{ variable_name }}

{%- if browser_enabled %}
- **browser** — browse web pages, take screenshots
{%- endif %}

{%- for skill in skills %}
  <skill>
    <name>{{ skill.name }}</name>
    <description>{{ skill.description }}</description>
  </skill>
{%- endfor %}

{%- if identity_context %}
{{ identity_context }}
{%- endif %}
```

--------------------------------

### Install Skill from a Local File

Source: https://docs.spacebot.sh/skills

Installs a skill from a local `.skill` file using the spacebot CLI. This is useful for installing custom or downloaded skills.

```bash
spacebot skill install path/to/skill.skill
```

--------------------------------

### Run Spacebot Daemon and Development Mode

Source: https://docs.spacebot.sh/quickstart

Commands to run Spacebot as a background daemon or in the foreground with debug logging. The foreground mode is recommended for development.

```bash
# 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
```

--------------------------------

### Install a Specific Skill from a Repository

Source: https://docs.spacebot.sh/skills

Installs a particular skill from a GitHub repository using the spacebot CLI. This allows for targeted installation of needed functionalities.

```bash
spacebot skill add anthropics/skills/pdf
```

--------------------------------

### Install GitHub Skill via CLI

Source: https://docs.spacebot.sh/skills

Shows how to install a GitHub skill using the spacebot CLI to enable workers to interact with GitHub. This command fetches the skill from the skills.sh registry.

```bash
spacebot skill add anthropics/skills/github
```

--------------------------------

### Install Skill to Instance-Level

Source: https://docs.spacebot.sh/skills

Installs a skill to the instance-level, making it available across all agents managed by Spacebot. This is achieved using the --instance flag with the spacebot CLI.

```bash
spacebot skill add vercel-labs/agent-skills --instance
```

--------------------------------

### Deploy to Fly.io

Source: https://docs.spacebot.sh/docker

Commands to initialize and deploy the Spacebot application to the Fly.io platform.

```bash
fly launch --image ghcr.io/spacedriveapp/spacebot:slim
fly volumes create spacebot_data --size 5
fly secrets set ANTHROPIC_API_KEY="sk-ant-..."
fly deploy
```

--------------------------------

### Example: Azure OpenAI Custom Provider

Source: https://docs.spacebot.sh/config

This example demonstrates configuring a custom LLM provider for Azure OpenAI services using the 'openai_responses' api_type. The base_url points to the Azure OpenAI endpoint, and the API key is sourced from an environment variable.

```toml
[llm.provider.azure_openai]
api_type = "openai_responses"
base_url = "https://my-azure-openai.openai.azure.com"
api_key = "env:AZURE_OPENAI_KEY"
name = "Azure OpenAI GPT-4"
```

--------------------------------

### Install Skill

Source: https://docs.spacebot.sh/skills

Installs a new skill for an agent from a specified source, typically a GitHub repository.

```APIDOC
## POST /api/agents/skills/install

### Description
Install a skill from GitHub.

### Method
POST

### Endpoint
`/api/agents/skills/install`

#### Request Body
- **agent_id** (string) - Required - The ID of the agent to install the skill for.
- **spec** (string) - Required - The specification of the skill to install (e.g., 'github-user/repo-name').
- **instance** (boolean) - Optional - If true, installs the skill at the instance level; otherwise, installs at the workspace level. Defaults to false.

### Request Example
```json
{
  "agent_id": "my-agent",
  "spec": "vercel-labs/agent-skills",
  "instance": false
}
```

### Response
#### Success Response (200)
- **installed** (array) - A list of skills that were successfully installed.

### Response Example
```json
{
  "installed": [
    "vercel-react-best-practices",
    "web-design-guidelines",
    "composition-patterns"
  ]
}
```
```

--------------------------------

### GET /metrics

Source: https://docs.spacebot.sh/metrics

Retrieves the current system metrics in Prometheus text exposition format (0.0.4).

```APIDOC
## GET /metrics

### Description
Returns the current state of all tracked metrics including LLM usage, tool calls, and memory operations in Prometheus format.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **Content-Type** (string) - text/plain; version=0.0.4

#### Response Example
# HELP spacebot_llm_requests_total Total LLM completion requests
# TYPE spacebot_llm_requests_total counter
spacebot_llm_requests_total{agent_id="1",model="gpt-4o",tier="worker"} 42
```

--------------------------------

### System Prompt Channel List Example

Source: https://docs.spacebot.sh/channels

Shows how available channels are formatted and injected into the system prompt for LLM context.

```text
## Available Channels

You can send messages to these channels using the `send_message_to_another_channel` tool:

- **general** (discord, id: `discord:123456:789012`)
- **dev** (discord, id: `discord:123456:789013`)
- **Jamie** (telegram, id: `telegram:551234`)
```

--------------------------------

### API Skill Management

Source: https://docs.spacebot.sh/skills

Examples of JSON payloads for listing installed skills and installing new skills via the Spacebot API.

```json
{
  "skills": [
    {
      "name": "pdf",
      "description": "Create, edit, and extract content from PDF files",
      "file_path": "/path/to/skills/pdf/SKILL.md",
      "base_dir": "/path/to/skills/pdf",
      "source": "instance"
    }
  ]
}
```

```json
{
  "agent_id": "my-agent",
  "spec": "vercel-labs/agent-skills",
  "instance": false
}
```

--------------------------------

### Rig Agent Construction (Rust)

Source: https://docs.spacebot.sh/architecture

Demonstrates how to build a Rig agent with a custom model, preamble, hooks, tool server handle, and default maximum turns. This is used for constructing agentic processes within Spacebot.

```rust
let agent = AgentBuilder::new(model.clone())
    .preamble(&system_prompt)
    .hook(SpacebotHook::new(process_id, process_type, event_tx.clone()))
    .tool_server_handle(tools.clone())
    .default_max_turns(50)
    .build();
```

--------------------------------

### Set LLM API Key via Environment Variable

Source: https://docs.spacebot.sh/quickstart

Sets the Anthropic API key as an environment variable. This is a quick way to configure Spacebot with LLM access without using a config file.

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

--------------------------------

### PromptEngine Initialization and Rendering (Rust)

Source: https://docs.spacebot.sh/prompts

Demonstrates how to create a PromptEngine instance and render static or variable-substituted templates. Assumes the engine is initialized with a language code and handles potential rendering errors.

```rust
// Create the engine (typically done once at startup)
let engine = PromptEngine::new("en")?;

// Render a static template
let worker_prompt = engine.render_static("worker")?;

// Render with variables
let channel_prompt = engine.render_channel_prompt(
    Some(identity_context),      // Option<String>
    Some(memory_bulletin),       // Option<String>
    Some(skills_prompt),         // Option<String>
    worker_capabilities,         // String
    conversation_context,        // Option<String>
    status_text                  // Option<String>
)?;
```

--------------------------------

### Set SPACEBOT_DIR Environment Variable with direnv

Source: https://docs.spacebot.sh/quickstart

This snippet shows how to use direnv to automatically set the `SPACEBOT_DIR` environment variable when entering the Spacebot project directory. This simplifies development by ensuring the correct data directory is used without manual intervention.

```bash
# .envrc in your spacebot source checkout
export SPACEBOT_DIR="$HOME/.spacebot/dev"
```

--------------------------------

### Example: Local LLM Server Provider

Source: https://docs.spacebot.sh/config

Configuration for connecting to a local LLM server using the 'openai_completions' api_type. The base_url is set to the local server address, and the API key is loaded from an environment variable. Note that '/v1' should not be included in the base_url for this type.

```toml
[llm.provider.local_llm]
api_type = "openai_completions"
base_url = "http://localhost:8080" # no /v1 in base_url
api_key = "env:LOCAL_LLM_KEY"
name = "Local LLaMA Server"
```

--------------------------------

### Building the OpenCode Embed Bundle

Source: https://docs.spacebot.sh/opencode

Instructions for building the embedded web UI for OpenCode workers using Node.js and bun. This process clones OpenCode, copies embed entry points, builds with Vite, and outputs to a gitignored directory.

```shell
# Requires Node 22+ and bun
./scripts/build-opencode-embed.sh
# or: just build-opencode-embed
```

```shell
eval "$(fnm env)" && fnm use v24.14.0 && ./scripts/build-opencode-embed.sh
```

--------------------------------

### Configure Spacebot Slack Integration (TOML)

Source: https://docs.spacebot.sh/slack-setup

This TOML configuration sets up Spacebot to use Slack as a messaging platform. It requires enabling the Slack integration and providing both a Bot Token and an App Token. The configuration can directly include tokens or reference environment variables for security.

```toml
[messaging.slack]
enabled = true
bot_token = "xoxb-your-bot-token"
app_token = "xapp-your-app-token"

[[bindings]]
agent_id = "main"
channel = "slack"

```

```toml
[messaging.slack]
enabled = true
bot_token = "env:SLACK_BOT_TOKEN"
app_token = "env:SLACK_APP_TOKEN"

```

--------------------------------

### Configure Spacebot Slack DM Filtering (TOML)

Source: https://docs.spacebot.sh/slack-setup

This TOML configuration allows Spacebot to process direct messages (DMs) from specific users. By listing user IDs in the `dm_allowed_users` array, you can control which users the bot will respond to in direct message conversations, enhancing privacy and control.

```toml
[messaging.slack]
dm_allowed_users = ["U01234", "U56789"]

```

--------------------------------

### Dynamic Tool Lifecycle Management

Source: https://docs.spacebot.sh/tools

Demonstrates the sequence of adding and removing dynamic tools during a conversation turn to ensure proper resource cleanup and context isolation.

```text
1. Message arrives on channel
2. Channel creates response_tx for this turn
3. add_channel_tools(handle, channel_id, response_tx, ...)
4. Agent processes the message (LLM calls tools)
5. remove_channel_tools(handle)
6. Response sender drops, turn is complete
```

--------------------------------

### Configure Spacebot Slack Channel Filtering (TOML)

Source: https://docs.spacebot.sh/slack-setup

This TOML configuration snippet demonstrates how to restrict Spacebot's operation to specific Slack channels within a workspace. It requires the workspace ID and a list of channel IDs to which the bot should respond. This helps in managing bot interactions and focusing its activity.

```toml
[[bindings]]
agent_id = "main"
channel = "slack"
workspace_id = "T01234ABCDE"
channel_ids = ["C0001", "C0002"]

```

--------------------------------

### Create Branch Tool Server ChannelStore Reference (Rust)

Source: https://docs.spacebot.sh/channels

Explains how each branch is provided with a ChannelStore reference to enable channel querying by the channel_recall tool.

```rust
`create_branch_tool_server`— Each branch gets a`ChannelStore` reference so the `channel_recall` tool can query channels.
```

--------------------------------

### Creating a New Template (Rust & Jinja)

Source: https://docs.spacebot.sh/prompts

Guides on how to create a new template file within the prompt system. This involves adding the `.md.j2` file to the appropriate language directory and registering it within the `PromptEngine` in `engine.rs`.

```jinja
# 1. Add the template file
# prompts/en/my_template.md.j2
You are a {{ role }}.

{%- if custom_instructions %}
{{ custom_instructions }}
{%- endif %}

```

```rust
# 2. Register in PromptEngine
# src/prompts/engine.rs
const MY_TEMPLATE: &str = include_str!("../../prompts/en/my_template.md.j2");

// In PromptEngine::new():
env.add_template("my_template", MY_TEMPLATE)?;

```

--------------------------------

### List Installed Skills

Source: https://docs.spacebot.sh/skills

Lists all skills currently installed in Spacebot, indicating whether they are installed at the workspace or instance level. The output includes the skill name and a brief description.

```bash
spacebot skill list
```

--------------------------------

### List Installed Skills

Source: https://docs.spacebot.sh/skills

Retrieves a list of all skills installed for a specific agent.

```APIDOC
## GET /api/agents/skills?agent_id={id}

### Description
List all installed skills for an agent.

### Method
GET

### Endpoint
`/api/agents/skills`

#### Query Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **skills** (array) - A list of installed skills.
  - **name** (string) - The name of the skill.
  - **description** (string) - A brief description of the skill.
  - **file_path** (string) - The file path to the skill's main documentation file (SKILL.md).
  - **base_dir** (string) - The base directory of the skill.
  - **source** (string) - The source of the skill (e.g., 'instance', 'workspace').

### Response Example
```json
{
  "skills": [
    {
      "name": "pdf",
      "description": "Create, edit, and extract content from PDF files",
      "file_path": "/path/to/skills/pdf/SKILL.md",
      "base_dir": "/path/to/skills/pdf",
      "source": "instance"
    }
  ]
}
```
```

--------------------------------

### PUT /agents/config

Source: https://docs.spacebot.sh/sandbox

Allows dynamic switching of the sandbox mode at runtime without restarting the agent.

```APIDOC
## PUT /agents/config

### Description
This endpoint allows for the dynamic modification of agent configuration, specifically the sandbox mode, at runtime. This enables flexibility without requiring agent restarts.

### Method
PUT

### Endpoint
/agents/config

### Parameters
#### Request Body
- **sandbox** (object) - Configuration related to the sandbox environment.
  - **mode** (string) - The desired sandbox mode. Possible values include "disabled", "enabled", etc. (specific values may vary).

### Request Example
```json
{
  "sandbox": { "mode": "disabled" }
}
```

### Response
#### Success Response (200)
Indicates that the configuration was successfully updated. The response body may be empty or contain confirmation details.

#### Response Example
(Response body may vary, often empty on success)
```json
{
}
```
```

--------------------------------

### Remove Installed Skill

Source: https://docs.spacebot.sh/skills

Removes an installed skill from the agent. Requires the agent ID and the name of the skill to remove.

```APIDOC
## DELETE /api/agents/skills/remove

### Description
Removes an installed skill from the agent.

### Method
DELETE

### Endpoint
/api/agents/skills/remove

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent from which to remove the skill.
- **name** (string) - Required - The name of the skill to remove.
```

--------------------------------

### Remove an Installed Skill

Source: https://docs.spacebot.sh/skills

Removes a specified skill from Spacebot's installation. This command uninstalls the skill, making its functionalities unavailable to agents.

```bash
spacebot skill remove pdf
```
Tokens:
Raw