Server Capabilities

HTTP server for LLM proxy, thread persistence, authentication, and weaver orchestration

Server Capabilities

The Loom server is a production-ready HTTP API that provides:

• LLM Proxy: Route requests to Anthropic/OpenAI with authentication
• Thread Persistence: Store and sync conversation history
• Weaver Orchestration: Manage ephemeral Kubernetes execution environments
• Crash Analytics: Error tracking and symbolication
• Cron Monitoring: Job scheduling and health checks
• Session Analytics: User session tracking and release health

Architecture

┌─────────────┐
│  loom CLI   │─────┐
└─────────────┘     │
                    ▼
┌─────────────┐  ┌──────────────┐  ┌─────────────┐
│  VS Code    │─▶│ loom-server  │─▶│  Postgres   │
└─────────────┘  └──────────────┘  └─────────────┘
                    │       │
                    ▼       ▼
              ┌──────┐  ┌─────────┐
              │ LLMs │  │ K8s Pod │
              └──────┘  └─────────┘

Starting the Server

Development

# Using cargo
cargo run --bin loom-server

# With custom config
LOOM_SERVER_PORT=8080 cargo run --bin loom-server

Production (Nix)

# Build with cargo2nix (faster incremental builds)
nix build .#loom-server-c2n

# Run
./result/bin/loom-server

Docker

# Build image
nix build .#loom-server-image

# Load into Docker
docker load < result

# Run container
docker run -p 8080:8080 \
  -e DATABASE_URL=postgres://... \
  loom-server:latest

Configuration

Server configuration is loaded from:

1. Environment variables (LOOM_SERVER_*)
2. .env file (via dotenvy)
3. Built-in defaults

Required Configuration

DATABASE_URL · string · required

PostgreSQL connection string

Example: postgres://user:pass@localhost/loom

HTTP Server

LOOM_SERVER_HOST · string

Bind address
Default: 0.0.0.0

LOOM_SERVER_PORT · integer

HTTP port
Default: 8080

Authentication

LOOM_SERVER_AUTH_DEV_MODE · boolean

Bypass authentication (development only)
Default: false

LOOM_SERVER_AUTH_SESSION_CLEANUP_INTERVAL_SECS · integer

Session cleanup job interval
Default: 3600 (1 hour)

LOOM_SERVER_AUTH_OAUTH_STATE_CLEANUP_INTERVAL_SECS · integer

OAuth state cleanup interval
Default: 300 (5 minutes)

Weaver Configuration

LOOM_SERVER_WEAVER_ENABLED · boolean

Enable weaver provisioning
Default: false

LOOM_SERVER_WEAVER_NAMESPACE · string

Kubernetes namespace for weavers
Default: loom-weavers

LOOM_SERVER_WEAVER_CLEANUP_INTERVAL_SECS · integer

Weaver TTL cleanup job interval
Default: 60 (1 minute)

Logging

LOOM_SERVER_LOGGING_LEVEL · string

Log level: trace, debug, info, warn, error
Default: info

Core APIs

Health Check

GET /health

Returns server status and version information.

Request

curl https://loom.ghuntley.com/health

{
  "status": "ok",
  "version": "0.1.0",
  "uptime_secs": 3600
}

LLM Proxy

POST /api/llm/complete

The LLM proxy routes requests to configured providers (Anthropic/OpenAI) while handling authentication, rate limiting, and token management.

Request:

{
  "provider": "anthropic",
  "model": "claude-3-5-sonnet-20241022",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "tools": [...],
  "stream": true
}

Streaming Response:

• Server-Sent Events (SSE)
• Event types: text_delta, tool_call_delta, completed, error

Thread APIs

Create/Update

POST /api/threads
PUT /api/threads/:id

Save or update a conversation thread with full state:

• Messages (user, assistant, tool)
• Agent state (waiting, executing, error)
• Git metadata (branch, commits, remote)
• Workspace info

Retrieve

GET /api/threads/:id

Fetch a single thread by ID.

List

GET /api/threads?limit=50

List threads for authenticated user, sorted by last activity.

Search

GET /api/threads/search?q=query&limit=20

Full-text search across:

• Message content
• Git branch/remote/commit
• Tags and metadata

Weaver APIs

See Weavers documentation for complete API reference.

# Create weaver
POST /api/weavers

# List weavers
GET /api/weavers

# Get weaver status
GET /api/weavers/:id

# Delete weaver
DELETE /api/weavers/:id

# Attach to weaver terminal
GET /api/weavers/:id/attach (WebSocket)

Background Jobs

The server runs scheduled background jobs using the JobScheduler:

Weaver Cleanup

Deletes expired weavers based on TTL
Interval: 60 seconds

Session Cleanup

Removes expired auth sessions
Interval: 1 hour

OAuth State Cleanup

Purges expired OAuth states
Interval: 5 minutes

Job History Cleanup

Archives old job execution logs
Interval: 24 hours

Token Refresh

Refreshes OAuth tokens for LLM pool
Interval: 5 minutes

SCM Maintenance

Runs git gc on SCM repositories
Interval: Configurable

Cron Monitoring

Detects missed runs and timeouts
Interval: 60 seconds

Session Aggregation

Aggregates app sessions into metrics
Interval: 1 hour

Database Schema

Migrations are in crates/loom-server/migrations/ as numbered SQL files:

001_initial.sql
002_threads.sql
003_auth.sql
004_weavers.sql
...

Migration workflow:

1. Create new file: NNN_description.sql
2. Run cargo2nix-update to regenerate Cargo.nix
3. Migrations auto-run on server startup

Always run cargo2nix-update after adding migrations! The Nix build doesn’t detect include_str! changes automatically.

Self-Monitoring

Loom uses itself for crash reporting:

// Automatically initialized on server startup
initialize_self_monitoring(
  &pool,
  &base_url,
  release,
  &environment,
).await

Creates crash projects for:

• loom-server (backend crashes)
• loom-web (frontend crashes)
• loom-cli (CLI crashes)

Deployment

NixOS Auto-Update

Production server runs NixOS with automatic deployment:

# Check deployment status
sudo systemctl status nixos-auto-update.service

# View logs
sudo journalctl -u nixos-auto-update.service -f

# Check deployed version
cat /var/lib/nixos-auto-update/deployed-revision

# Force rebuild
sudo rm /var/lib/nixos-auto-update/deployed-revision
sudo systemctl start nixos-auto-update.service

Deployment flow:

1. Push to trunk branch
2. Auto-update service polls every 10 seconds
3. Pulls latest commit
4. Rebuilds with Nix
5. Switches to new configuration
6. Restarts loom-server.service

Verify Deployment

1. Check revision

   cat /var/lib/nixos-auto-update/deployed-revision
   
2. Check service status

   sudo systemctl status loom-server
   

   Look for recent start time.

3. Test health endpoint

   curl -s https://loom.ghuntley.com/health | jq .
   

Monitoring

Logs

# Server logs
sudo journalctl -u loom-server -f

# Last 100 lines
sudo journalctl -u loom-server -n 100

# Filter by level
sudo journalctl -u loom-server -p err

Admin UI

The server includes a log streaming endpoint for admin dashboards:

GET /api/admin/logs/stream

Returns Server-Sent Events with structured log entries (redacted secrets).

Security

Authentication

• OAuth 2.0: GitHub, Google providers
• Magic Links: Email-based passwordless auth
• Session Tokens: Secure, httpOnly cookies
• API Keys: For programmatic access

Secrets Management

All secrets use loom-common-secret::SecretString:

• Auto-redacts in Debug/Display/Serialize
• Access via .expose() only when needed
• Never logged by tracing instrumentation

CORS

Configured to allow:

• Any origin (development)
• Any methods
• Any headers

Production deployments should restrict CORS to trusted domains.

Performance

Database Connection Pooling

let pool = loom_server::db::create_pool(&database_url).await?;

Uses sqlx::PgPool with:

• Automatic connection management
• Prepared statement caching
• Health checks

Caching

• Thread Store: In-memory cache for recent threads
• Docs Index: Loaded once on startup
• Job Scheduler: Periodic task execution without polling

Troubleshooting

Server won't start

Check PostgreSQL connection:

psql $DATABASE_URL -c "SELECT 1;"

Verify migrations:

ls crates/loom-server/migrations/

Weaver provisioning fails

Check Kubernetes access:

sudo kubectl get pods -n loom-weavers

Verify namespace exists:

sudo kubectl get namespace loom-weavers

LLM proxy errors

Enable debug logging:

LOOM_SERVER_LOGGING_LEVEL=debug ./loom-server

Check provider credentials in database.