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
Production (Nix)
Docker

# Using cargo
cargo run --bin loom-server

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

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

# Run
./result/bin/loom-server

# 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:

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

Required Configuration

DATABASE_URL

string

required

PostgreSQL connection stringExample: 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.

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

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
Retrieve
List
Search

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

GET /api/threads/:id

Fetch a single thread by ID.

GET /api/threads?limit=50

List threads for authenticated user, sorted by last activity.

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:

Create new file: NNN_description.sql
Run cargo2nix-update to regenerate Cargo.nix
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:

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

Verify Deployment

Check revision

cat /var/lib/nixos-auto-update/deployed-revision

Check service status

sudo systemctl status loom-server

Look for recent start time.

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.

Get Started

Core Features

Architecture

Integrations

Observability

Deployment

​Server Capabilities

​Architecture

​Starting the Server

​Configuration

​Required Configuration

​HTTP Server

​Authentication

​Weaver Configuration

​Logging

​Core APIs

​Health Check

​LLM Proxy

​Thread APIs

​Weaver APIs

​Background Jobs

Weaver Cleanup

Session Cleanup

OAuth State Cleanup

Job History Cleanup

Token Refresh

SCM Maintenance

Cron Monitoring

Session Aggregation

​Database Schema

​Self-Monitoring

​Deployment

​NixOS Auto-Update

​Verify Deployment

​Monitoring

​Logs

​Admin UI

​Security

​Authentication

​Secrets Management

​CORS

​Performance

​Database Connection Pooling

​Caching

​Troubleshooting

Build docs developers (and LLMs) love

Server Capabilities

Architecture

Starting the Server

Configuration

Required Configuration

HTTP Server

Authentication

Weaver Configuration

Logging

Core APIs

Health Check

LLM Proxy

Thread APIs

Weaver APIs

Background Jobs

Database Schema

Self-Monitoring

Deployment

NixOS Auto-Update

Verify Deployment

Monitoring

Logs

Admin UI

Security

Authentication

Secrets Management

CORS

Performance

Database Connection Pooling

Caching

Troubleshooting