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

> Deploy SpacetimeDB applications with a single command to Maincloud or self-hosted instances. Learn how to publish your Wasm or JS modules seamlessly.

- Repository: [Clockwork Labs/SpacetimeDB](https://github.com/clockworklabs/SpacetimeDB)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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:

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

```

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

```bash
spacetime publish -s maincloud my-cool-module

```

The CLI performs the following steps as defined in [`crates/cli/src/subcommands/publish.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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
// TypeScript
import { DbConnection } from "@spacetimedb/client";
const conn = DbConnection.builder()
  .withUri('https://maincloud.spacetimedb.com')
  .withModuleName('my-cool-module');

```

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

```

```rust
// 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:

```bash
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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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`:

```ini
[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:

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

```bash
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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/cli/src/subcommands/publish.rs) | CLI publish command implementation, schema building, pre-publish checks | [view](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/cli/src/subcommands/publish.rs) |
| [`crates/standalone/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/standalone/src/lib.rs) | Server-side "publish" RPC handling, database identity verification | [view](https://github.com/clockworklabs/SpacetimeDB/blob/master/crates/standalone/src/lib.rs#L261-L280) |
| [`templates/basic-rs/spacetimedb/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/templates/basic-rs/spacetimedb/src/lib.rs) | Minimal Rust module example (schema + reducer) used in tutorials | [view](https://github.com/clockworklabs/SpacetimeDB/blob/master/templates/basic-rs/spacetimedb/src/lib.rs) |
| [`docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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](https://github.com/clockworklabs/SpacetimeDB/blob/master/docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00100-maincloud.md) |
| [`docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00200-self-hosting.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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](https://github.com/clockworklabs/SpacetimeDB/blob/master/docs/versioned_docs/version-1.12.0/00300-resources/00100-how-to/00100-deploy/00200-self-hosting.md) |
| `images/basic-architecture-diagram.png` | Visual summary of the runtime-module-client stack | [view](https://github.com/clockworklabs/SpacetimeDB/blob/master/images/basic-architecture-diagram.png) |

## 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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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`](https://github.com/clockworklabs/SpacetimeDB/blob/main/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.