Server Setup

The TraceVault server provides centralized storage, team-wide visibility, and a web UI for browsing AI session traces.

Quick Start

Using Docker

docker run -d \
  --name tracevault \
  -p 8080:8080 \
  -v tracevault-data:/data \
  ghcr.io/softwaremill/tracevault-server:latest

Using the binary

# Download the server binary
curl -fsSL https://tracevault.dev/install-server.sh | sh

# Start the server
tracevault-server --data-dir /var/lib/tracevault --port 8080

Configuration

The server is configured via a TOML file or environment variables.

# /etc/tracevault/server.toml
[server]
host = "0.0.0.0"
port = 8080
data_dir = "/var/lib/tracevault"

[auth]
enabled = true
method = "token"  # "token", "oidc", or "none"

[storage]
backend = "sqlite"  # "sqlite" or "postgres"
# For postgres:
# connection_string = "postgresql://user:pass@localhost/tracevault"

[retention]
max_age_days = 365
max_storage_gb = 50

Environment Variables

All config keys can be set as environment variables with the TRACEVAULT_ prefix:

Authentication

Token-based auth

Generate API tokens for CLI clients:

tracevault-server token create --name "ci-bot" --scope "push"

Configure the CLI to use the token:

tracevault remote add https://your-server.example.com --token <token>

OIDC

For enterprise deployments, TraceVault supports OpenID Connect:

[auth]
method = "oidc"

[auth.oidc]
issuer = "https://your-idp.example.com"
client_id = "tracevault"
client_secret = "secret"

Web UI

The server includes a built-in web UI accessible at the server's root URL. It provides:

• Session timeline with search and filters
• Diff viewer for code changes
• Full conversation thread viewer
• Team activity dashboard
• Policy management

Deployment

Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name tracevault.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

systemd Service

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

[Service]
Type=simple
ExecStart=/usr/local/bin/tracevault-server --config /etc/tracevault/server.toml
Restart=always
User=tracevault

[Install]
WantedBy=multi-user.target