Skip to content

Overhaul README with up-to-date content #4500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
clockwork-labs-bot wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Overhaul README with up-to-date content #4500

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dc72947
Overhaul README with up-to-date content
clockwork-labs-bot Feb 28, 2026
130cc3e
Apply suggestions from code review
cloutiertyler Mar 1, 2026
7d1a661
Merge remote-tracking branch 'origin/master' into bot/update-readme
clockwork-labs-bot Mar 1, 2026
64d28fe
Address review: simplify Quick Start to use spacetime dev --template
clockwork-labs-bot Mar 1, 2026
e02666d
Simplify Quick Start: remove redundant publish step
clockwork-labs-bot Mar 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 116 additions & 155 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@
<a href="https://crates.io/crates/spacetimedb"><img src="https://img.shields.io/crates/d/spacetimedb?color=e45928&label=Rust%20Crate&style=flat-square"></a>
&nbsp;
<a href="https://www.nuget.org/packages/SpacetimeDB.Runtime"><img src="https://img.shields.io/nuget/dt/spacetimedb.runtime?color=0b6cff&label=NuGet%20Package&style=flat-square"></a>
&nbsp;
<a href="https://www.npmjs.com/package/spacetimedb"><img src="https://img.shields.io/npm/dm/spacetimedb?color=cb0000&label=npm&style=flat-square"></a>
</p>
<p align="center">
<a href="https://discord.gg/spacetimedb"><img src="https://img.shields.io/discord/1037340874172014652?label=discord&style=flat-square&color=5a66f6"></a>
Expand Down Expand Up @@ -63,15 +65,15 @@

<br>

## What is [SpacetimeDB](https://spacetimedb.com)?
## What is SpacetimeDB?

You can think of SpacetimeDB as both a database and server combined into one.
SpacetimeDB is a relational database that is also a server. You upload your application logic directly into the database, and clients connect to it without any server in between.

It is a relational database system that lets you upload your application logic directly into the database by way of fancy stored procedures called "modules."
Write your schema and business logic as a **module** in [Rust](https://spacetimedb.com/docs/quickstarts/rust), [C#](https://spacetimedb.com/docs/quickstarts/c-sharp), [TypeScript](https://spacetimedb.com/docs/quickstarts/typescript), or [C++](https://spacetimedb.com/docs/quickstarts/cpp). SpacetimeDB compiles it, runs it inside the database, and automatically synchronizes state to connected clients in real-time.

Instead of deploying a web or game server that sits in between your clients and your database, your clients connect directly to the database and execute your application logic inside the database itself. You can write all of your permission and authorization logic right inside your module just as you would in a normal server.
Instead of deploying a web or game server that sits in between your clients and your database, your clients connect directly to the database and execute your application logic in your module. You can write all of your permission and authorization logic right inside your module just as you would in a normal server.

This means that you can write your entire application in a single language, Rust, and deploy it as a single binary. No more microservices, no more containers, no more Kubernetes, no more Docker, no more VMs, no more DevOps, no more infrastructure, no more ops, no more servers.
This means that you can write your entire application in a single language and deploy it as a single binary. No more separate webserver, no more containers, no more Kubernetes, no more VMs, no more DevOps, no more caching later. Zero infrastructure to manage.

<figure>
<img src="./images/basic-architecture-diagram.png" alt="SpacetimeDB Architecture" style="width:100%">
Expand All @@ -80,214 +82,173 @@ This means that you can write your entire application in a single language, Rust
</figcaption>
</figure>

It's actually similar to the idea of smart contracts, except that SpacetimeDB is a database, has nothing to do with blockchain, and is orders of magnitude faster than any smart contract system.

So fast, in fact, that the entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) is just a SpacetimeDB module. We don't have any other servers or services running, which means that everything in the game, all of the chat messages, items, resources, terrain, and even the locations of the players are stored and processed by the database before being synchronized out to all of the clients in real-time.

SpacetimeDB is optimized for maximum speed and minimum latency rather than batch processing or OLAP workloads. It is designed to be used for real-time applications like games, chat, and collaboration tools.

This speed and latency is achieved by holding all of application state in memory, while persisting the data in a write-ahead-log (WAL) which is used to recover application state.

## Installation

You can run SpacetimeDB as a standalone database server via the `spacetime` CLI tool.
Install instructions for supported platforms are outlined below.
The same install instructions can be found on our website at https://spacetimedb.com/install.

#### Install on macOS

Installing on macOS is as simple as running our install script. After that you can use the spacetime command to manage versions.

```bash
curl -sSf https://install.spacetimedb.com | sh
```
SpacetimeDB is optimized for maximum speed and minimum latency. SpacetimeDB provides all the ACID guarantees of a traditional RDBMS, with all the speed of an optimized web server. All application state is held in memory for fast access, while a commit log on disk provides durability and crash recovery. The entire backend of our MMORPG [BitCraft Online](https://bitcraftonline.com) runs as a single SpacetimeDB module: chat, items, terrain, player positions, everything, synchronized to thousands of players in real-time.

#### Install on Linux
## Quick Start

Installing on Linux is as simple as running our install script. After that you can use the spacetime command to manage versions.
### 1. Install

```bash
# macOS / Linux
curl -sSf https://install.spacetimedb.com | sh
```

#### Install on Windows

Installing on Windows is as simple as pasting the snippet below into PowerShell. If you would like to use WSL instead, please follow the Linux install instructions.

```ps1
# Windows (PowerShell)
iwr https://windows.spacetimedb.com -useb | iex
```

#### Installing from Source

A quick note on installing from source: we recommend that you don't install from source unless there is a feature that is available in `master` that hasn't been released yet, otherwise follow the official installation instructions.

##### MacOS + Linux

Installing on macOS + Linux is pretty straightforward. First we are going to build all of the binaries that we need:
### 2. Log in

```bash
# Install rustup, you can skip this step if you have cargo and the wasm32-unknown-unknown target already installed.
curl https://sh.rustup.rs -sSf | sh
# Clone SpacetimeDB
git clone https://github.com/clockworklabs/SpacetimeDB
# Build and install the CLI
cd SpacetimeDB
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli

# Create directories
mkdir -p ~/.local/bin
export STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION

# Install the update binary
cp target/release/spacetimedb-update ~/.local/bin/spacetime
cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION
cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION
spacetime login
```

At this stage you'll need to add ~/.local/bin to your path if you haven't already.
This opens a browser to authenticate with GitHub. Your identity is linked to your account so you can publish databases.

```
# Please add the following line to your shell configuration and open a new shell session:
export PATH="$HOME/.local/bin:$PATH"
### 3. Start developing

```bash
spacetime dev --template chat-react-ts
```

Then finally set your SpacetimeDB version:
```
That is it. This creates a project from a template, publishes it to [Maincloud](https://spacetimedb.com/docs/how-to/deploy/maincloud), and watches for file changes, automatically rebuilding and republishing on save. See [pricing](https://spacetimedb.com/pricing) for details.

# Then, in a new shell, set the current version:
spacetime version use $STDB_VERSION
## How It Works

# If STDB_VERSION is not set anymore then you can use the following command to list your versions:
spacetime version list
```
SpacetimeDB modules define **tables** (your data) and **reducers** (your logic). Clients connect, call reducers, and subscribe to tables. When data changes, SpacetimeDB pushes updates to subscribed clients automatically.

You can verify that the correct version has been installed via `spacetime --version`.
```rust
// Define a table
#[spacetimedb::table(accessor = messages, public)]
pub struct Message {
#[primary_key]
#[auto_inc]
id: u64,
sender: Identity,
text: String,
}

##### Windows
// Define a reducer (your API endpoint)
#[spacetimedb::reducer]
pub fn send_message(ctx: &ReducerContext, text: String) {
ctx.db.messages().insert(Message {
id: 0,
sender: ctx.sender,
text,
});
}
```

Building on windows is a bit more complicated. You'll need a slightly different version of perl compared to what comes pre-bundled in most Windows terminals. We recommend [Strawberry Perl](https://strawberryperl.com/). You may also need access to an `openssl` binary which actually comes pre-installed with [Git for Windows](https://git-scm.com/downloads/win). Also, you'll need to install [rustup](https://rustup.rs/) for Windows.
On the client side, subscribe and get live updates:

In a Git for Windows shell you should have something that looks like this:
```
$ which perl
/c/Strawberry/perl/bin/perl
$ which openssl
/mingw64/bin/openssl
$ which cargo
/c/Users/<user>/.cargo/bin/cargo
```typescript
const [messages] = useTable(tables.message);
// messages updates automatically when the server state changes.
// No polling. No refetching.
```

If that looks correct then you're ready to proceed!
## Language Support

```powershell
# Clone SpacetimeDB
git clone https://github.com/clockworklabs/SpacetimeDB
### Server Modules

# Build and install the CLI
cd SpacetimeDB
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli
Write your database logic in any of these languages:

# Create directories
$stdbDir = "$HOME\AppData\Local\SpacetimeDB"
$stdbVersion = & ".\target\release\spacetimedb-cli" --version | Select-String -Pattern 'spacetimedb tool version ([0-9.]+);' | ForEach-Object { $_.Matches.Groups[1].Value }
New-Item -ItemType Directory -Path "$stdbDir\bin\$stdbVersion" -Force | Out-Null
| Language | Quickstart |
|----------|-----------|
| **Rust** | [Get started](https://spacetimedb.com/docs/quickstarts/rust) |
| **C#** | [Get started](https://spacetimedb.com/docs/quickstarts/c-sharp) |
| **TypeScript** | [Get started](https://spacetimedb.com/docs/quickstarts/typescript) |
| **C++** | [Get started](https://spacetimedb.com/docs/quickstarts/cpp) |

# Install the update binary
Copy-Item "target\release\spacetimedb-update.exe" "$stdbDir\spacetime.exe"
Copy-Item "target\release\spacetimedb-cli.exe" "$stdbDir\bin\$stdbVersion\"
Copy-Item "target\release\spacetimedb-standalone.exe" "$stdbDir\bin\$stdbVersion\"
### Client SDKs

```
Connect from any of these platforms:

Now add the directory we just created to your path. We recommend adding it to the system path because then it will be available to all of your applications (including Unity3D). After you do this, restart your shell!
| SDK | Quickstart |
|-----|-----------|
| **TypeScript** (React, Next.js, Vue, Svelte, Angular, Node.js, Bun, Deno) | [Get started](https://spacetimedb.com/docs/quickstarts/react) |
| **Rust** | [Get started](https://spacetimedb.com/docs/quickstarts/rust) |
| **C#** (standalone and Unity) | [Get started](https://spacetimedb.com/docs/quickstarts/c-sharp) |
| **C++** (Unreal Engine) | [Get started](https://spacetimedb.com/docs/quickstarts/cpp) |

```
%USERPROFILE%\AppData\Local\SpacetimeDB
```
## Running with Docker

Then finally, open a new shell and use the installed SpacetimeDB version:
```
spacetime version use $stdbVersion

# If stdbVersion is no longer set, list versions using the following command:
spacetime version list
```bash
docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start
```

You can verify that the correct version has been installed via `spacetime --version`.
## Building from Source

If you're using Git for Windows you can follow these instructions instead:
If you need features from `master` that have not been released yet:

```bash
# Clone SpacetimeDB
# Prerequisites: Rust toolchain with wasm32-unknown-unknown target
curl https://sh.rustup.rs -sSf | sh

git clone https://github.com/clockworklabs/SpacetimeDB
# Build and install the CLI
cd SpacetimeDB
# Build the CLI binaries - this takes a while on windows so go grab a coffee :)
cargo build --locked --release -p spacetimedb-standalone -p spacetimedb-update -p spacetimedb-cli

# Create directories
export STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
mkdir -p ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION

# Install the update binary
cp target/release/spacetimedb-update ~/AppData/Local/SpacetimeDB/spacetime
cp target/release/spacetimedb-cli ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION
cp target/release/spacetimedb-standalone ~/AppData/Local/SpacetimeDB/bin/$STDB_VERSION

# Now add the directory we just created to your path. We recommend adding it to the system path because then it will be available to all of your applications (including Unity3D). After you do this, restart your shell!
# %USERPROFILE%\AppData\Local\SpacetimeDB

# Set the current version
spacetime version use $STDB_VERSION
```

You can verify that the correct version has been installed via `spacetime --version`.

#### Running with Docker
Then install the binaries:

If you prefer to run Spacetime in a container, you can use the following command to start a new instance.
<details>
<summary>macOS / Linux</summary>

```bash
docker run --rm --pull always -p 3000:3000 clockworklabs/spacetime start
```

## Documentation

For more information about SpacetimeDB, getting started guides, game development guides, and reference material please see our [documentation](https://spacetimedb.com/docs).
mkdir -p ~/.local/bin
STDB_VERSION="$(./target/release/spacetimedb-cli --version | sed -n 's/.*spacetimedb tool version \([0-9.]*\);.*/\1/p')"
mkdir -p ~/.local/share/spacetime/bin/$STDB_VERSION

## Getting Started
cp target/release/spacetimedb-update ~/.local/bin/spacetime
cp target/release/spacetimedb-cli ~/.local/share/spacetime/bin/$STDB_VERSION
cp target/release/spacetimedb-standalone ~/.local/share/spacetime/bin/$STDB_VERSION

We've prepared several getting started guides in each of our supported languages to help you get up and running with SpacetimeDB as quickly as possible. You can find them on our [docs page](https://spacetimedb.com/docs).
# Add to your shell config if not already present:
export PATH="$HOME/.local/bin:$PATH"

In summary there are only 4 steps to getting started with SpacetimeDB.
# Set the active version:
spacetime version use $STDB_VERSION
```
</details>

1. Install the `spacetime` CLI tool.
2. Start a SpacetimeDB standalone node with `spacetime start`.
3. Write and upload a module in one of our supported module languages.
4. Connect to the database with one of our client libraries.
<details>
<summary>Windows (PowerShell)</summary>

You can see a summary of the supported languages below with a link to the getting started guide for each.
```powershell
$stdbDir = "$HOME\AppData\Local\SpacetimeDB"
$stdbVersion = & ".\target\release\spacetimedb-cli" --version |
Select-String -Pattern 'spacetimedb tool version ([0-9.]+);' |
ForEach-Object { $_.Matches.Groups[1].Value }
New-Item -ItemType Directory -Path "$stdbDir\bin\$stdbVersion" -Force | Out-Null

## Language Support
Copy-Item "target\release\spacetimedb-update.exe" "$stdbDir\spacetime.exe"
Copy-Item "target\release\spacetimedb-cli.exe" "$stdbDir\bin\$stdbVersion\"
Copy-Item "target\release\spacetimedb-standalone.exe" "$stdbDir\bin\$stdbVersion\"

You can write SpacetimeDB modules in several popular languages, with more to come in the future!
# Add to your system PATH: %USERPROFILE%\AppData\Local\SpacetimeDB
# Then in a new shell:
spacetime version use $stdbVersion
```
</details>

#### Serverside Libraries
Verify with `spacetime --version`.

- [Rust](https://spacetimedb.com/docs/modules/rust/quickstart)
- [C#](https://spacetimedb.com/docs/modules/c-sharp/quickstart)
## Documentation

#### Client Libraries
Full documentation is available at **[spacetimedb.com/docs](https://spacetimedb.com/docs)**, including:

- [Rust](https://spacetimedb.com/docs/sdks/rust/quickstart)
- [C#](https://spacetimedb.com/docs/sdks/c-sharp/quickstart)
- [Typescript](https://spacetimedb.com/docs/sdks/typescript/quickstart)
- [Quickstart guides](https://spacetimedb.com/docs) for every supported language and framework
- [Core concepts](https://spacetimedb.com/docs/core-concepts): tables, reducers, subscriptions, authentication
- [Tutorials](https://spacetimedb.com/docs/tutorials/chat-app): chat app, Unity multiplayer, Unreal Engine multiplayer
- [Deployment guide](https://spacetimedb.com/docs/how-to/deploy/maincloud): publishing to Maincloud
- [CLI reference](https://spacetimedb.com/docs/reference/cli-reference)
- [SQL reference](https://spacetimedb.com/docs/reference/sql-reference)

## License

SpacetimeDB is licensed under the BSL 1.1 license. This is not an open source or free software license, however, it converts to the AGPL v3.0 license with a linking exception after a few years.
SpacetimeDB is licensed under the [Business Source License 1.1 (BSL)](LICENSE.txt). It converts to the AGPL v3.0 with a linking exception after a few years. The linking exception means you are **not** required to open-source your own code if you use SpacetimeDB. You only need to contribute back changes to SpacetimeDB itself.

**Why did we choose this license?**
We chose to license SpacetimeDB under the MariaDB Business Source License for 4 years because we can't compete with AWS while also building our products for them.

Note that the AGPL v3.0 does not typically include a linking exception. We have added a custom linking exception to the AGPL license for SpacetimeDB. Our motivation for choosing a free software license is to ensure that contributions made to SpacetimeDB are propagated back to the community. We are expressly not interested in forcing users of SpacetimeDB to open source their own code if they link with SpacetimeDB, so we needed to include a linking exception.
We chose GPLv3 with linking exception as the open source license because we want contributions merged back into mainline (just like Linux), but we don't want to make anyone else open source their own code (i.e. linking exception).
Loading