Installation

From source (recommended for development)

Requirements

Tool	Version	Notes
Rust	1.85+	rustup install 1.85
WASM target	—	rustup target add wasm32-unknown-unknown
Bun	1.x	TypeScript SDK and CLI scripts

Build

git clone https://github.com/cosmictron/cosmictron
cd cosmictron
cargo build --release \
  -p cosmictron-server \
  -p cosmictron-cli

Binaries are placed in target/release/:

• cosmictron-server — the main server process
• cosmictron-cli — project scaffolding, deploy, and dev tooling

Add them to your PATH:

export PATH="$PATH:$(pwd)/target/release"

Docker

docker pull ghcr.io/cosmictron/cosmictron:latest

docker run -p 3000:3000 \
  -e COSMICTRON_DATA_DIR=/data \
  -v cosmictron-data:/data \
  ghcr.io/cosmictron/cosmictron:latest

The container exposes:

• 3000 — WebSocket + HTTP REST
• 5432 — PgWire (Postgres wire protocol)

Environment variables

Variable	Default	Description
COSMICTRON_DATA_DIR	./data	Path for WAL, snapshots, and blobs
COSMICTRON_LISTEN	0.0.0.0:3000	WebSocket/HTTP bind address
COSMICTRON_PGWIRE_LISTEN	0.0.0.0:5432	PgWire bind address
COSMICTRON_FSYNC_POLICY	periodic	always, periodic, or never
COSMICTRON_PERFORMANCE_PROFILE	balanced	development, balanced, production, maximum_safety
COSMICTRON_LOG	info	Log level: trace, debug, info, warn, error
COSMICTRON_JWT_SECRET	—	JWT signing secret for auth tokens
COSMICTRON_MODULE_PATH	—	Path to module source (for dev hot-reload)

Tip

Use COSMICTRON_PERFORMANCE_PROFILE=production for production deployments. It sets fsync=always, enables fdatasync, and tightens memory limits.

Kubernetes

A minimal Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cosmictron
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cosmictron
  template:
    metadata:
      labels:
        app: cosmictron
    spec:
      containers:
        - name: cosmictron
          image: ghcr.io/cosmictron/cosmictron:latest
          ports:
            - containerPort: 3000
            - containerPort: 5432
          env:
            - name: COSMICTRON_PERFORMANCE_PROFILE
              value: production
          livenessProbe:
            httpGet:
              path: /v1/health
              port: 3000
          readinessProbe:
            httpGet:
              path: /v1/health/ready
              port: 3000
          volumeMounts:
            - name: data
              mountPath: /data
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: cosmictron-data

Caution

Cosmictron is currently a single-node runtime. Multi-region distributed deployments are on the roadmap (Coming Soon). Plan your storage accordingly.

TypeScript SDK

bun add @cosmictron/client
# or
npm install @cosmictron/client

The SDK package ships:

• CosmictronClient — WebSocket connection + reducer calls + subscriptions
• React hooks (useQuery, useReducer) — for frontend apps
• Auth helpers — signIn, signUp, useIdentity