Skip to main content

​
Overview

Loom server is the HTTP API server that handles thread persistence, LLM proxy, authentication, and weaver provisioning. It can be deployed using NixOS (recommended), Docker, or as a standalone binary.

​
Deployment Methods

NixOS

Production-ready with auto-updates

Docker

Containerized deployment

Binary

Manual installation

​
NixOS Deployment

The production Loom server runs on NixOS with automatic git-based deployments. Pushing to trunk triggers a rebuild within 10 seconds.

​
Installation

1

Import the Loom server module

Add to your NixOS configuration:
configuration.nix
{ config, pkgs, ... }:
{
  imports = [
    ./loom-server.nix  # Import from infra/nixos-modules/loom-server.nix
  ];
}
2

Enable and configure the service

configuration.nix
services.loom-server = {
  enable = true;
  package = pkgs.loom-server;
  
  # Network configuration
  host = "0.0.0.0";
  port = 8080;
  baseUrl = "https://loom.example.com";
  
  # Database
  databasePath = "/var/lib/loom-server/loom.db";
  
  # Logging
  logLevel = "info";
  defaultLocale = "en";
};
3

Configure LLM providers

Enable at least one LLM provider:
configuration.nix
services.loom-server.anthropic = {
  enable = true;
  apiKeyFile = "/run/secrets/anthropic-api-key";
  model = "claude-sonnet-4-20250514";
};

services.loom-server.openai = {
  enable = true;
  apiKeyFile = "/run/secrets/openai-api-key";
  model = "gpt-4o";
};
API keys are loaded from files, not inline values. Store keys in /run/secrets/ using agenix or sops-nix.
4

Deploy the configuration

sudo nixos-rebuild switch
5

Verify the service is running

sudo systemctl status loom-server
curl http://localhost:8080/health

​
Auto-Update Service

The production deployment uses nixos-auto-update.service for automatic deployments:
nixos-auto-update.nix
services.nixos-auto-update = {
  enable = true;
  repoUrl = "https://github.com/your-org/loom";
  branch = "trunk";
  interval = "10s";  # Check for updates every 10 seconds
};
Monitoring deployments: 
sudo journalctl -u nixos-auto-update.service -f

​
Docker Deployment

Loom provides a multi-stage Dockerfile that builds both the Rust server and Svelte web UI.

​
Building the Image

cd /path/to/loom
docker build -f docker/Dockerfile -t loom-server:latest .

​
Running the Container

docker run -d \
  --name loom-server \
  -p 8080:8080 \
  -v loom-data:/var/lib/loom \
  -e LOOM_SERVER_HOST=0.0.0.0 \
  -e LOOM_SERVER_PORT=8080 \
  -e LOOM_SERVER_DATABASE_URL=sqlite:/var/lib/loom/loom.db \
  -e LOOM_SERVER_ANTHROPIC_API_KEY=sk-... \
  -e LOOM_SERVER_ANTHROPIC_MODEL=claude-sonnet-4-20250514 \
  loom-server:latest

​
Docker Compose

docker-compose.yml
version: '3.8'

services:
  loom-server:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8080:8080"
    volumes:
      - loom-data:/var/lib/loom
    environment:
      LOOM_SERVER_HOST: 0.0.0.0
      LOOM_SERVER_PORT: 8080
      LOOM_SERVER_DATABASE_URL: sqlite:/var/lib/loom/loom.db
      LOOM_SERVER_BASE_URL: https://loom.example.com
      LOOM_SERVER_ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      LOOM_SERVER_ANTHROPIC_MODEL: claude-sonnet-4-20250514
      RUST_LOG: info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

volumes:
  loom-data:

​
Standalone Binary

​
Building from Source

1

Install Rust toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable
2

Clone the repository

git clone https://github.com/your-org/loom.git
cd loom
3

Build loom-server

cargo build --release --package loom-server
The binary will be at ./target/release/loom-server
4

Run the server

export LOOM_SERVER_HOST=127.0.0.1
export LOOM_SERVER_PORT=8080
export LOOM_SERVER_DATABASE_URL=sqlite:loom.db
export LOOM_SERVER_ANTHROPIC_API_KEY=sk-...

./target/release/loom-server

​
Using Nix

Build with Nix for reproducible binaries: 
# Build server binary
nix build .#loom-server-c2n
./result/bin/loom-server --version

# Build Docker image
nix build .#loom-server-image
docker load < result

​
Health Checks

The server provides a /health endpoint for monitoring: 
curl http://localhost:8080/health
Response: 
{
  "status": "ok",
  "version": "0.1.0",
  "database": "connected",
  "uptime_seconds": 12345
}

​
Troubleshooting

Check the logs:
# NixOS
sudo journalctl -u loom-server -n 100

# Docker
docker logs loom-server

# Standalone
# Logs go to stdout - check your terminal or systemd journal
Common issues:
  • Database file permissions
  • Port already in use (check with ss -tlnp | grep :8080)
  • Missing API keys
  • Invalid database path
Migrations run automatically on startup. If they fail:
  1. Check database file permissions
  2. Ensure the directory exists and is writable
  3. Check disk space
  4. Review migration logs for specific errors
Force migration retry:
# Stop the server
sudo systemctl stop loom-server

# Backup the database
cp /var/lib/loom-server/loom.db /var/lib/loom-server/loom.db.backup

# Restart the server (migrations run on startup)
sudo systemctl start loom-server
If you see Address already in use errors:
# Find what's using the port
sudo ss -tlnp | grep :8080

# Kill the process
sudo kill <pid>

# Or use a different port
export LOOM_SERVER_PORT=9090

​
Security Hardening

The NixOS module includes security hardening via systemd: 
serviceConfig = {
  NoNewPrivileges = true;
  ProtectSystem = "strict";
  ProtectHome = true;
  PrivateTmp = true;
  PrivateDevices = true;
  ProtectKernelTunables = true;
  ProtectKernelModules = true;
  ProtectControlGroups = true;
  RestrictAddressFamilies = [ "AF_INET" "AF_INET6" "AF_UNIX" ];
  RestrictNamespaces = true;
  MemoryDenyWriteExecute = true;
  SystemCallFilter = [ "@system-service" "~@privileged" ];
};

​
Next Steps

Configure Environment Variables

Complete configuration reference

Setup Kubernetes for Weavers

Deploy weaver execution environments

Database Migrations

Manage schema changes

Authentication

Configure OAuth and SSO

Build docs developers (and LLMs) love

Get started for freeTalk to us