JN
•4 min read

Self-Hosting SpaceBot: My Setup Guide

#ai-agent#openrouter

Introduction

I discovered spacebot when Jamie posted this short intro video on twitter. OpenClaw has had all the headlines, but despite installing it myself, it never really stuck... I didn't really know it, but Jamie's video touch on all the reasons why... and gave solid answers! I had to try it immediately..

I wanted to run it on my own hardware rather than in the cloud and since I had a spare laptop to hand I decided to turn it into a dedicated spacebot server.

The work is done, so i thought I'd document the process. Here's what we'll cover:

  • Setting up SpaceBot on a Linux Server
  • Configuring it to be accessible from anywhere on the local network with a freindly URL
  • Ensuring it stays up to date with nightly auto-updates

If you are also starting from a bare machine, there's an appendix covering my Ubuntu Server installation and configuration steps.

Prerequisites

  • A Linux server (Ubuntu Server 24.04 LTS recommended) with SSH access
  • An OpenRouter API key (or other supported LLM provider)
  • A Discord bot token (if using Discord)

Step 1: Install Build Dependencies

Spacebot is written in Rust and currently needs to be compiled from source. These packages provide the C compiler, linker, and libraries that Rust's build system needs.

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential pkg-config libssl-dev protobuf-compiler unzip

Step 2: Install Rust and Bun

Rust compiles spacebot itself. Bun builds the React frontend that gets embedded into the binary - without it you'd have a working API but no web dashboard.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

Step 3: Clone, Build, Install

This clones the repo, builds the frontend, compiles the Rust binary, and installs it to ~/.cargo/bin/ so it's available as spacebot from anywhere. The first build compiles ~1080 crates and takes a while - go make a coffee. Don't worry, subsequent builds are much faster.

git clone https://github.com/spacedriveapp/spacebot.git ~/spacebot
cd ~/spacebot/interface && bun install && bun add -d @rollup/rollup-linux-x64-gnu && bun run build
cd ~/spacebot && cargo build --release
cargo install --path .

Step 4: Configure

Spacebot needs at minimum an LLM provider key and an agent definition. You can either run spacebot start -f with no config for interactive onboarding, or create ~/.spacebot/config.toml manually for full control:

[api]
bind = "0.0.0.0" # By default, the API only listens on localhost. This allows access from other machines on the network.

[llm]
openrouter_key = "env:OPENROUTER_API_KEY"

[defaults.routing] # Choose your own model configuration
channel = "openrouter/z-ai/glm-5"
branch = "openrouter/z-ai/glm-5"
worker = "openrouter/minimax/minimax-m2.5"
compactor = "openrouter/minimax/minimax-m2.5"
cortex = "openrouter/minimax/minimax-m2.5"

[[agents]]
id = "my-agent"
default = true

[messaging.discord]
enabled = true
token = "env:DISCORD_BOT_TOKEN"
dm_allowed_users = ["YOUR_DISCORD_USER_ID"]

[[bindings]]
agent_id = "my-agent"
channel = "discord"
guild_id = "YOUR_GUILD_ID"

Model Choice:

As per the SpaceBot docs (use a capable model for channel/branch and a cheap/fast model for worker/compactor/cortex, I decided to use Z.AIs GLM-5 model as my capable model and Minimax M2.5 as my cheap/fast model for everything else. If it works out well I might move to Z.AIs coding plan directly, but for now I want to see how things perform and tweak as i go.

Step 5: Systemd Service

During setup i waas running spacebot via a ssh session.. using sytstemd ensures it starts automatically on boot and restarts itself if it crashes.

Create /etc/systemd/system/spacebot.service:

[Unit]
Description=Spacebot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=youruser
ExecStart=/home/youruser/.cargo/bin/spacebot start -f
Restart=on-failure
RestartSec=5
Environment=HOME=/home/youruser

[Install]
WantedBy=multi-user.target

Use start -f (foreground) - systemd needs to own the process directly. Don't let spacebot daemonize itself.

sudo systemctl daemon-reload && sudo systemctl enable spacebot && sudo systemctl start spacebot

Step 6: Local DNS

I wanted to be able to access SpaceBot from any device on my local network without remembering an IP address or port.

I have a unifi network so I was able to go into the dashboard and set a fixed ip address and give it a local DNS record

Step 7: Caddy Reverse Proxy

By default SpaceBot serves its web UI on port 19898. Caddy sits in front of it and proxies port 80 so you can access it at a clean URL without remembering a port number. It's a single binary with zero config beyond a three-line Caddyfile.

sudo apt install -y caddy

/etc/caddy/Caddyfile:

http://space.bot {
    reverse_proxy localhost:19898
}

sudo systemctl restart caddy

Step 8: Nightly Auto-Updates

Spacebot is actively developed and changing fast... so keeping up to date means pulling the latest source, rebuilding, and restarting the service. This script automates the entire process. A systemd timer triggers it nightly at your chosen time - if there are no changes in git, it's effectively a no-op.

~/update-spacebot.sh:

#!/bin/bash
set -e

cd ~/spacebot
git pull
cd interface && bun install && bun run build
cd ~/spacebot
cargo build --release
cargo install --path .
sudo systemctl restart spacebot

chmod +x ~/update-spacebot.sh

Systemd timer for nightly runs at 3am. Add passwordless sudo for the restart only:

# /etc/sudoers.d/spacebot
youruser ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart spacebot

We can trigger this manually if required: sudo systemctl start spacebot-update.service

Gotchas

Things I hit along the way that aren't obvious from the docs (at the time of writing..) - PR incoming to add these to the official docs, but in the meantime, here they are:

  • protobuf-compiler not in docs --> sudo apt install protobuf-compiler
  • Bun missing Rollup platform binary --> bun add -d @rollup/rollup-linux-x64-gnu
  • API only on localhost by default --> Add [api] bind = "0.0.0.0"

Appendix: Ubuntu Server Setup

For anyone starting from a fresh machine (spare laptop, old desktop, etc.).

Choosing an OS

Ubuntu Server 24.04 LTS. Five years of support, no desktop environment, SSH out of the box. Other options considered:

  • Arch: rolling release, more maintenance
  • Debian: older packages
  • Fedora Server: shorter support cycles (13 months)

Creating the Bootable USB

  • Download Ubuntu Server 24.04 LTS ISO (amd64 for Intel/AMD machines)
  • Flash to USB with Balena Etcher

BIOS Configuration

My Dell needed some BIOS changes before Ubuntu could see the drive:

  • Switch SATA/storage mode from RAID to AHCI
  • Disable Secure Boot
  • Changing these may trigger a BitLocker recovery prompt from Windows - ignore it if you're wiping the drive - but proceed with care

Installation

  • Boot from USB (Dell: F12 for one-time boot menu)
  • Select "Ubuntu Server" (not minimized)
  • Set a hostname (e.g. spacebotserver)
  • Enable OpenSSH server
  • Skip Ubuntu Pro

Headless Configuration

Disable lid suspend so the laptop runs with the lid closed:

sudo sed -i 's/#HandleLidSwitch=suspend/HandleLidSwitch=ignore/' /etc/systemd/logind.conf
sudo systemctl restart systemd-logind

Network

If using WiFi, create a netplan config:

# /etc/netplan/01-wifi.yaml
network:
  version: 2
  wifis:
    [your-wifi-interface-name]: # e.g. wlan0 - check with `ip a`
      dhcp4: true
      access-points:
        "Your WiFi Name":
          password: "your-password"

sudo netplan apply

Note: the /etc/netplan/ directory may not exist on a fresh install - create it with mkdir -p /etc/netplan.

Leave a comment