Skip to main content

Self-Hosting

Run your own Treeship instance for maximum control and trust minimization.

Quick Start with Docker

# Clone the repo
git clone https://github.com/treeship-dev/treeship.git
cd treeship/treeship-api

# Generate a signing key
python -c "
from signing import KeyPair
import base64
kp = KeyPair.generate()
print('TREESHIP_SIGNING_KEY=' + base64.b64encode(kp.to_pem()).decode())
print('Key ID:', kp.key_id)
"

# Create .env file
cat > .env << EOF
DATABASE_URL=sqlite+aiosqlite:///./treeship.db
TREESHIP_SIGNING_KEY=your-base64-key-here
TREESHIP_API_KEY=your-api-key-here
TREESHIP_WEB_URL=https://your-domain.com
EOF

# Run with Docker
docker build -t treeship-api .
docker run -p 8000:8000 --env-file .env treeship-api

Deploy to Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
cd treeship-api
railway up

# Set environment variables in Railway dashboard

Configuration

Required Environment Variables

VariableDescription
DATABASE_URLDatabase connection string
TREESHIP_API_KEYAPI key for authenticated endpoints

Optional Environment Variables

VariableDefaultDescription
TREESHIP_WEB_URLhttps://treeship.devBase URL for verification links
TREESHIP_SIGNING_KEYAuto-generatedBase64-encoded PEM private key
TREESHIP_KEY_PATH~/.treeship/signing.keyPath to key file (dev only)

Database Options

SQLite (Development)

DATABASE_URL=sqlite+aiosqlite:///./treeship.db

PostgreSQL (Production)

DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/treeship

Key Management

Generate a New Key

from treeship_api.signing import KeyPair
import base64

kp = KeyPair.generate()
print("Private key (keep secret):")
print(base64.b64encode(kp.to_pem()).decode())
print("\nKey ID:", kp.key_id)
print("\nPublic key (share freely):")
print(kp.public_key_pem())

Key Rotation

  1. Generate new key
  2. Update TREESHIP_SIGNING_KEY
  3. Restart the service
  4. Old attestations remain verifiable (store old public keys)

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Agents    │────▶│  Treeship   │────▶│  Database   │
│             │     │    API      │     │             │
└─────────────┘     └─────────────┘     └─────────────┘


                    ┌─────────────┐
                    │  Verifiers  │
                    │  (public)   │
                    └─────────────┘

Health Checks

# Check API health
curl http://localhost:8000/health
# {"status":"ok","version":"0.1.0"}

# Check public key
curl http://localhost:8000/v1/pubkey

Scaling

The API is stateless except for the signing key. Scale horizontally by:
  1. Using a shared PostgreSQL database
  2. Setting the same TREESHIP_SIGNING_KEY on all instances
  3. Load balancing across instances