Deploying SpacetimeDB Applications: A Complete Guide to Maincloud and Self-Hosting

Deploying SpacetimeDB applications requires a single spacetime publish command that compiles your module to Wasm or JavaScript, runs pre-publish migration checks, and uploads the artifact to either the managed Maincloud service or a self-hosted instance.

Deploying SpacetimeDB applications involves publishing a module containing your schema, reducers, and business logic directly to the database runtime. Whether you choose the fully managed Maincloud service or run your own standalone server, the deployment workflow remains consistent and is driven by the spacetime CLI tool from the clockworklabs/SpacetimeDB repository.

Understanding the SpacetimeDB Deployment Architecture

SpacetimeDB merges a relational database with an application server, allowing you to write business logic directly in the module that runs inside the database. The deployment architecture consists of three core components:

• The Module: Contains your schema definitions, reducers, and procedures compiled to Wasm or JavaScript.
• The SpacetimeDB Runtime: Hosts the module and provides WebSocket and Postgres wire-compatible APIs.
• Clients: Use language-specific SDKs (TypeScript, C#, Rust, etc.) to connect to the runtime and invoke reducers.

The publish flow is implemented in crates/cli/src/subcommands/publish.rs, where the CLI builds a CommandSchema for the publish sub-command and orchestrates the deployment process.

Deploying to Maincloud (Managed Service)

Maincloud is the managed hosting option for SpacetimeDB applications, providing automatic scaling, HTTPS, TLS termination, and zero-operations hosting ideal for SaaS products and rapid prototypes.

Installing the CLI and Publishing

First, install the spacetime CLI tool:

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

Then publish your module to Maincloud using the -s maincloud flag:

spacetime publish -s maincloud my-cool-module

The CLI performs the following steps as defined in crates/cli/src/subcommands/publish.rs (lines 644-686):

1. Compiles your module to Wasm or JavaScript
2. Runs a pre-publish check via /v1/database/{db}/pre_publish that computes a migration plan
3. Aborts on breaking schema changes unless --delete-data or --yes flags are supplied
4. Uploads the artifact and activates the new module instantly

Connecting Client SDKs to Maincloud

After deployment, clients connect using the SDK builder pattern. The connection URI follows the same structure across all supported languages:

// TypeScript
import { DbConnection } from "@spacetimedb/client";
const conn = DbConnection.builder()
  .withUri('https://maincloud.spacetimedb.com')
  .withModuleName('my-cool-module');

// C#
var conn = DbConnection.Builder()
  .WithUri("https://maincloud.spacetimedb.com")
  .WithModuleName("my-cool-module");

// Rust
let conn = DbConnection::builder()
  .with_uri("https://maincloud.spacetimedb.com")
  .with_module_name("my-cool-module");

Deploying Self-Hosted SpacetimeDB Applications

Self-hosting provides full control over the binary, custom networking configurations, and on-premises deployment for regulatory environments or private clouds.

Installing the Runtime as a System Service

Create a dedicated system user and installation directory:

sudo mkdir /stdb
sudo useradd --system spacetimedb
sudo chown -R spacetimedb:spacetimedb /stdb

# Install the binary under that user

sudo -u spacetimedb bash -c 'curl -sSf https://install.spacetimedb.com | sh -s -- --root-dir /stdb --yes'

The server-side publish handling is implemented in crates/standalone/src/lib.rs (lines 261-280), which processes the upload and manages database identity verification.

Configuring systemd for Production

Create a systemd service file at /etc/systemd/system/spacetimedb.service:

[Unit]
Description=SpacetimeDB Server
After=network.target

[Service]
ExecStart=/stdb/spacetime --root-dir=/stdb start --listen-addr='127.0.0.1:3000'
Restart=always
User=spacetimedb
WorkingDirectory=/stdb

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable spacetimedb
sudo systemctl start spacetimedb

Publishing to Your Local Instance

With the server running locally, publish without the -s flag (defaults to localhost:3000):

spacetime publish my-local-module

Clients connect to http://127.0.0.1:3000 (or your configured address) using the same SDK builder pattern shown for Maincloud, substituting the local URI.

Key Implementation Files and References

Path	Role	Direct link
crates/cli/src/subcommands/publish.rs	CLI publish command implementation, schema building, pre-publish checks	view
crates/standalone/src/lib.rs	Server-side "publish" RPC handling, database identity verification	view
templates/basic-rs/spacetimedb/src/lib.rs	Minimal Rust module example (schema + reducer) used in tutorials	view
docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md	User-facing Maincloud deployment guide (CLI usage & SDK connection)	view
docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00200-self-hosting.md	Self-hosting tutorial (systemd service, Nginx reverse proxy)	view
images/basic-architecture-diagram.png	Visual summary of the runtime-module-client stack	view

Summary

• Unified workflow: Deploying SpacetimeDB applications uses the same spacetime publish command for both Maincloud and self-hosted targets, differing only in the server endpoint.
• Pre-publish safety: The CLI automatically runs migration checks via /v1/database/{db}/pre_publish to prevent breaking schema changes unless explicitly overridden with --delete-data or --yes flags.
• Zero-downtime activation: New modules activate instantly upon upload, with existing clients continuing to work against the previous version until they reconnect.
• Flexible hosting: Choose Maincloud for automatic scaling and zero operations, or self-host using the systemd configuration defined in the official documentation for full control over the runtime environment.

Frequently Asked Questions

What is the difference between Maincloud and self-hosting for SpacetimeDB applications?

Maincloud is the fully managed service operated by Clockwork Labs that provides automatic scaling, HTTPS/TLS termination, and zero-operations hosting ideal for SaaS products and rapid prototyping. Self-hosting involves running the spacetime binary on your own infrastructure—either on-premises or in a private cloud—giving you full control over networking, security policies, and hardware resources as implemented in crates/standalone/src/lib.rs.

How does the spacetime publish command handle database migrations?

The publish command performs a pre-publish check by calling the /v1/database/{db}/pre_publish endpoint, which computes a migration plan comparing the current database schema against the new module. If breaking changes are detected—such as column deletions or type alterations—the CLI aborts the deployment unless you provide the --delete-data flag to drop conflicting tables or --yes to force the migration. This safety mechanism is defined in crates/cli/src/subcommands/publish.rs (lines 644-686).

Can I deploy SpacetimeDB applications written in languages other than Rust?

Yes. While the templates/basic-rs/spacetimedb/src/lib.rs template demonstrates Rust, SpacetimeDB supports modules written in any language that compiles to WebAssembly (Wasm) or JavaScript. The CLI compilation step in crates/cli/src/subcommands/publish.rs handles the build process for supported languages, and the resulting artifact is uploaded to the runtime regardless of the source language.

What happens to connected clients during a SpacetimeDB deployment?

SpacetimeDB deployments are zero-downtime for existing connections. When you publish a new module version, the runtime activates it instantly, but clients connected to the previous version continue operating against that version until they reconnect. Once a client reconnects, it automatically begins using the new module version with the updated schema and reducers. This behavior ensures continuous service availability during updates to both Maincloud and self-hosted instances.

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