How to Install SpacetimeDB: Complete CLI Setup Guide for Windows, macOS, and Linux

You can install SpacetimeDB by running the official one-liner script—curl -sSf https://install.spacetimedb.com | sh on macOS/Linux or iwr https://windows.spacetimedb.com -useb | iex in PowerShell on Windows—which downloads the versioned binaries and creates a spacetime shim in your local bin directory.

SpacetimeDB is a relational database that also runs your application logic as a server, managing data and code execution in a single unified system. The installation process centers on the spacetime command-line interface (CLI), a thin wrapper around three Rust binaries maintained in the clockworklabs/SpacetimeDB repository. Once installed, the CLI handles authentication, local server management, and module deployment to the hosted Maincloud service.

Installing the SpacetimeDB CLI

The official installer script supports macOS, Linux, and Windows, automatically detecting your platform and downloading the appropriate pre-built binaries. The script installs a version manager that stores releases under ~/.local/share/spacetime/bin/<version> (or %USERPROFILE%\AppData\Local\SpacetimeDB on Windows) and creates a spacetime executable shim in your system PATH.

macOS and Linux Installation

Run the installation script using curl:

curl -sSf https://install.spacetimedb.com | sh

The installer places the spacetime shim in ~/.local/bin. Ensure this directory is on your $PATH—the script outputs a line you can copy into your shell configuration file (such as ~/.bashrc or ~/.zshrc) to complete the setup.

Windows Installation

For Windows systems, execute the PowerShell installer:

iwr https://windows.spacetimedb.com -useb | iex

This creates the SpacetimeDB directory at %USERPROFILE%\AppData\Local\SpacetimeDB and installs spacetime.exe. Add this folder to your system PATH environment variable to run the command from any terminal session.

Verify the Installation

Confirm the CLI is accessible by checking its version:

spacetime --version

Expect output similar to spacetimedb tool version X.Y.Z, indicating the specific release installed by the version manager.

Understanding the SpacetimeDB Binary Architecture

According to the clockworklabs/SpacetimeDB source code, the CLI comprises three distinct Rust binaries that work together to provide database and application functionality:

• spacetime-cli – Parses commands, manages authentication, and orchestrates module builds. Built from crates/cli/Cargo.toml.
• spacetime-update – Handles updates and version selection, allowing you to switch between releases. Built from crates/standalone/Cargo.toml as part of the standalone package.
• spacetime-standalone – The actual database server that executes WebAssembly modules and manages the in-memory store and commit log. Built from crates/standalone/Cargo.toml.

This architecture separates concerns between client interaction, version management, and server execution, enabling the version manager to isolate different releases and prevent dependency conflicts.

Authenticating and Running Your First Server

After installation, authenticate with the hosted Maincloud service to enable publishing modules:

spacetime login

A browser window opens to authorize via GitHub, storing an authentication token in ~/.config/spacetime/token.json.

To run a local development server:

spacetime start

The standalone server listens on port 3000 by default, handling database operations and module hosting locally. You can now point client SDKs (such as the TypeScript SDK) to http://localhost:3000 for development.

Building from Source (Optional)

For unreleased features or platform-specific compilation, build the three primary crates directly from the repository:

1. Install the Rust toolchain and add the WebAssembly target:

curl https://sh.rustup.rs -sSf | sh
rustup target add wasm32-unknown-unknown

2. Clone the repository and compile the binaries:

git clone https://github.com/clockworklabs/SpacetimeDB
cd SpacetimeDB
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetime-cli

3. Copy the resulting binaries to your local bin directories following the post-build installation steps outlined in the repository's README (lines 94-110), placing the versioned binaries in ~/.local/share/spacetime/bin/<VERSION> and the spacetime shim in ~/.local/bin.

Summary

• One-line installation: Use curl for macOS/Linux or PowerShell iwr for Windows to download the official installer from install.spacetimedb.com or windows.spacetimedb.com.
• Three-binary architecture: The CLI wraps spacetime-cli (command parsing), spacetime-update (version management), and spacetime-standalone (database server) as defined in crates/cli/Cargo.toml and crates/standalone/Cargo.toml.
• Version management: The installer stores releases in ~/.local/share/spacetime/bin/<version> and supports switching versions via spacetime version use <VERSION>.
• Quick start: Run spacetime login to authenticate, then spacetime start to launch a local server on port 3000.
• Source builds: Compile with cargo build --locked --release targeting the three primary crates for custom installations.

Frequently Asked Questions

Where does the SpacetimeDB installer place the binary files?

The installer creates a versioned directory at ~/.local/share/spacetime/bin/<version> on Unix systems or %USERPROFILE%\AppData\Local\SpacetimeDB on Windows, storing the three Rust binaries separately. It then creates a spacetime shim in ~/.local/bin (Unix) or adds the SpacetimeDB directory to your system PATH (Windows) to expose the CLI globally.

How do I switch between different versions of SpacetimeDB?

Use the built-in version manager by running spacetime version use <VERSION>. The spacetime-update binary—defined in crates/standalone/Cargo.toml—manages multiple installed versions in the local share directory, allowing you to roll back or upgrade without conflicts.

Can I install SpacetimeDB without using the official installer script?

Yes, you can build from source using Cargo. Clone the clockworklabs/SpacetimeDB repository, install the Rust toolchain with the wasm32-unknown-unknown target, and run cargo build --locked --release targeting -p spacetimedb-standalone, -p spacetimedb-update, and -p spacetime-cli. Then manually copy the binaries to your PATH following the README's building from source instructions.

What is the difference between spacetime start and the Maincloud service?

spacetime start launches the spacetime-standalone binary locally, running an in-memory database server with persistent commit logs on disk for development. Maincloud is the hosted production service managed by Clockwork Labs, accessed after running spacetime login for publishing modules to a remote infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}