Hosting Options

Traceway runs as a single binary. How you deploy it depends on your needs.

Local development

The fastest way to get started. No Docker, no cloud account, no authentication.

cargo install traceway
traceway serve

This starts:

• API server on http://localhost:3000
• Proxy on http://localhost:3001

Storage is SQLite (written to ./traceway.db in the current directory). Auth is disabled entirely — anyone who can reach the port can read and write data. This is designed for local development only.

import { Traceway } from 'traceway';

// No API key needed in local mode
const tw = new Traceway();

Changing the data directory

By default, the SQLite database is created in the current working directory. To change this:

TRACEWAY_DATA_DIR=/path/to/data traceway serve

Docker

Run Traceway in a container with persistent storage:

docker run -p 3000:3000 -p 3001:3001 ghcr.io/blastgits/traceway:latest

For persistent data across container restarts, mount a volume:

version: '3'
services:
  traceway:
    image: ghcr.io/blastgits/traceway:latest
    ports:
      - "3000:3000"
      - "3001:3001"
    volumes:
      - traceway-data:/data
    environment:
      - TRACEWAY_DATA_DIR=/data

volumes:
  traceway-data:

This runs in local mode (SQLite, no auth). To enable cloud mode in Docker, add the environment variables described below.

Cloud mode

For production deployments, run with --cloud to enable authentication, multi-tenancy, and cloud storage:

traceway serve --cloud

Cloud mode changes the storage architecture:

Each organization and project gets its own Turbopuffer namespace (tw_{org}_{project}), so data is fully isolated between tenants.

Required environment variables

Optional environment variables

Deploy to Railway

Traceway is deployed on Railway at api.traceway.ai. To run your own instance:

1. Create a new project on Railway.
2. Add a Postgres database from the Railway marketplace.
3. Deploy the Docker image ghcr.io/blastgits/traceway:latest.
4. Set the required environment variables above. Railway provides DATABASE_URL automatically when you link the Postgres database.
5. Set the start command to traceway serve --cloud.
6. Expose port 3000. Railway handles TLS termination.

Health checks

Configure Railway's health check to use:

Multiple replicas

Traceway supports running multiple replicas behind a load balancer. Each instance maintains an in-memory cache of data that is synced from the backend on startup. If you configure REDIS_URL, real-time events (SSE) are distributed across instances via Redis Pub/Sub. Without Redis, each instance only sees events from its own requests.

Plans and limits

Span limits are enforced per-organization. When you hit the limit, new spans are rejected with 402 Payment Required. Plan changes take effect immediately.

Building from source

git clone https://github.com/blastgits/traceway.git
cd traceway
cargo build --release -p api
./target/release/traceway serve

The full workspace includes a FUSE filesystem crate that requires macFUSE on macOS. If you don't need that, build only the packages you need:

cargo build --release -p api -p proxy -p trace

Ports