Configuration Reference

Configuration Sources

Loom server loads configuration from multiple sources with the following precedence (highest to lowest):

Environment variables (LOOM_SERVER_*)
Configuration file (/etc/loom/server.toml)
Built-in defaults

All configuration can be set via environment variables, NixOS module options, or TOML file.

HTTP Server

Basic Settings

LOOM_SERVER_HOST

string

default:"127.0.0.1"

Address to bind the HTTP server to. Use 0.0.0.0 to listen on all interfaces.

LOOM_SERVER_PORT

integer

default:"8080"

Port to listen on.

LOOM_SERVER_BASE_URL

string

default:"http://localhost:8080"

Base URL of the server (e.g., https://loom.example.com). Used for OAuth redirect URIs and email links.

Example

export LOOM_SERVER_HOST=0.0.0.0
export LOOM_SERVER_PORT=8080
export LOOM_SERVER_BASE_URL=https://loom.example.com

Database

LOOM_SERVER_DATABASE_URL

string

default:"sqlite:loom.db"

SQLite database connection string. Must start with sqlite:.

SQLite Options

# Read-write-create mode (default)
export LOOM_SERVER_DATABASE_URL=sqlite:/var/lib/loom-server/loom.db?mode=rwc

# Custom journal mode
export LOOM_SERVER_DATABASE_URL=sqlite:/var/lib/loom-server/loom.db?mode=rwc&journal_mode=WAL

# In-memory (testing only)
export LOOM_SERVER_DATABASE_URL=sqlite::memory:

Database migrations run automatically on server startup. The server will fail to start if migrations fail.

LLM Providers

Configure at least one LLM provider. The server supports Anthropic, OpenAI, Vertex AI, and Z.ai.

Anthropic Claude

LOOM_SERVER_ANTHROPIC_API_KEY

string

Anthropic API key (starts with sk-ant-).

LOOM_SERVER_ANTHROPIC_MODEL

string

default:"claude-sonnet-4-20250514"

Model identifier to use.

LOOM_SERVER_ANTHROPIC_OAUTH_ENABLED

boolean

default:"false"

Enable OAuth pool mode for Claude Max subscriptions (mutually exclusive with API_KEY).

LOOM_SERVER_ANTHROPIC_OAUTH_CREDENTIAL_FILE

string

default:"/var/lib/loom-server/anthropic-credentials.json"

Path to OAuth credential store when using pool mode.

OpenAI

LOOM_SERVER_OPENAI_API_KEY

string

OpenAI API key (starts with sk-).

LOOM_SERVER_OPENAI_MODEL

string

default:"gpt-4o"

Model identifier to use.

LOOM_SERVER_OPENAI_ORG

string

OpenAI organization ID for enterprise accounts.

Vertex AI (Google)

GOOGLE_APPLICATION_CREDENTIALS

string

Path to Google Cloud service account credentials JSON file.

LOOM_SERVER_VERTEX_PROJECT_ID

string

Google Cloud project ID.

LOOM_SERVER_VERTEX_LOCATION

string

default:"us-central1"

Google Cloud region.

Z.ai (ZhipuAI)

LOOM_SERVER_ZAI_API_KEY

string

Z.ai API key.

LOOM_SERVER_ZAI_MODEL

string

default:"glm-4.7"

Model identifier to use.

Authentication

General Settings

LOOM_SERVER_SIGNUPS_DISABLED

boolean

default:"false"

Disable new user signups. Existing users can still log in.

LOOM_SERVER_AUTH_DEV_MODE

boolean

default:"false"

Enable development mode (auto-authenticate without OAuth). Never use in production.

LOOM_SERVER_DEFAULT_LOCALE

string

default:"en"

Default locale for emails and user-facing content (en, es, ar).

GitHub OAuth

LOOM_SERVER_GITHUB_CLIENT_ID

string

GitHub OAuth application client ID.

LOOM_SERVER_GITHUB_CLIENT_SECRET

string

GitHub OAuth application client secret.

LOOM_SERVER_GITHUB_REDIRECT_URI

string

OAuth callback URL. Defaults to {baseUrl}/auth/github/callback.

Google OAuth

LOOM_SERVER_GOOGLE_CLIENT_ID

string

Google OAuth application client ID.

LOOM_SERVER_GOOGLE_CLIENT_SECRET

string

Google OAuth application client secret.

LOOM_SERVER_GOOGLE_REDIRECT_URI

string

OAuth callback URL. Defaults to {baseUrl}/auth/google/callback.

Okta OAuth (Enterprise SSO)

LOOM_SERVER_OKTA_DOMAIN

string

Okta domain (e.g., your-org.okta.com).

LOOM_SERVER_OKTA_CLIENT_ID

string

Okta OAuth application client ID.

LOOM_SERVER_OKTA_CLIENT_SECRET

string

Okta OAuth application client secret.

Weaver Provisioning

LOOM_SERVER_WEAVER_ENABLED

boolean

default:"false"

Enable Kubernetes-based weaver provisioning.

LOOM_SERVER_WEAVER_K8S_NAMESPACE

string

default:"loom-weavers"

Kubernetes namespace for weavers.

KUBECONFIG

string

default:"/etc/rancher/k3s/k3s.yaml"

Path to kubeconfig file.

LOOM_SERVER_WEAVER_CLEANUP_INTERVAL_SECS

integer

default:"1800"

Interval in seconds between cleanup runs for expired weavers.

LOOM_SERVER_WEAVER_DEFAULT_TTL_HOURS

integer

default:"4"

Default TTL in hours for weavers.

LOOM_SERVER_WEAVER_MAX_TTL_HOURS

integer

default:"48"

Maximum TTL in hours for weavers.

LOOM_SERVER_WEAVER_MAX_CONCURRENT

integer

default:"64"

Maximum number of concurrent weavers.

LOOM_SERVER_WEAVER_READY_TIMEOUT_SECS

integer

default:"60"

Timeout in seconds waiting for weaver to become ready.

LOOM_SERVER_WEAVER_IMAGE_PULL_SECRETS

string

Comma-separated list of Kubernetes secret names for pulling private images (e.g., ghcr-secret).

Audit Sidecar

LOOM_SERVER_WEAVER_AUDIT_ENABLED

boolean

default:"true"

Enable eBPF audit sidecar for weavers.

LOOM_SERVER_WEAVER_AUDIT_IMAGE

string

default:"ghcr.io/ghuntley/loom-audit-sidecar:latest"

Container image for audit sidecar.

LOOM_SERVER_WEAVER_AUDIT_BATCH_INTERVAL_MS

integer

default:"100"

Event batch interval in milliseconds.

LOOM_SERVER_WEAVER_AUDIT_BUFFER_MAX_BYTES

integer

default:"268435456"

Maximum local buffer size in bytes (256 MB).

SMTP Email

LOOM_SERVER_SMTP_HOST

string

default:"127.0.0.1"

SMTP server hostname.

LOOM_SERVER_SMTP_PORT

integer

default:"2525"

SMTP server port.

LOOM_SERVER_SMTP_USERNAME

string

SMTP username for authentication.

LOOM_SERVER_SMTP_PASSWORD

string

SMTP password for authentication.

LOOM_SERVER_SMTP_FROM_ADDRESS

string

Email address to send from (e.g., [email protected]).

LOOM_SERVER_SMTP_FROM_NAME

string

default:"Loom"

Display name for sent emails.

LOOM_SERVER_SMTP_USE_TLS

boolean

default:"false"

Use TLS for SMTP connection.

GitHub App Integration

LOOM_SERVER_GITHUB_APP_ID

string

GitHub App ID.

LOOM_SERVER_GITHUB_APP_PRIVATE_KEY

string

GitHub App private key (PEM format).

LOOM_SERVER_GITHUB_APP_WEBHOOK_SECRET

string

GitHub webhook secret for verifying payloads.

LOOM_SERVER_GITHUB_APP_SLUG

string

default:"loom"

GitHub App slug (appears in installation URLs).

LOOM_SERVER_GITHUB_APP_BASE_URL

string

default:"https://api.github.com"

GitHub API base URL (for GitHub Enterprise Server).

Search Providers

Google Custom Search Engine

LOOM_SERVER_GOOGLE_CSE_API_KEY

string

Google API key.

LOOM_SERVER_GOOGLE_CSE_SEARCH_ENGINE_ID

string

Google Custom Search Engine ID.

Serper.dev

LOOM_SERVER_SERPER_API_KEY

string

Serper API key.

Background Jobs

LOOM_SERVER_JOB_ALERT_ENABLED

boolean

default:"false"

Enable email alerts for job failures.

LOOM_SERVER_JOB_ALERT_RECIPIENTS

string

Comma-separated list of email recipients for job failure alerts.

LOOM_SERVER_JOB_HISTORY_RETENTION_DAYS

integer

default:"90"

Number of days to retain job run history.

LOOM_SERVER_SESSION_CLEANUP_INTERVAL_SECS

integer

default:"3600"

Interval in seconds between session cleanup runs.

LOOM_SERVER_OAUTH_STATE_CLEANUP_INTERVAL_SECS

integer

default:"900"

Interval in seconds between OAuth state cleanup runs.

Git Repository Maintenance

LOOM_SERVER_SCM_MAINTENANCE_ENABLED

boolean

default:"true"

Enable periodic git maintenance (gc, prune, repack, fsck) on SCM repositories.

LOOM_SERVER_SCM_MAINTENANCE_INTERVAL_SECS

integer

default:"86400"

Interval in seconds between maintenance runs (24 hours).

LOOM_SERVER_SCM_MAINTENANCE_STAGGER_MS

integer

default:"100"

Delay in milliseconds between processing each repository.

SCIM Provisioning

LOOM_SERVER_SCIM_ENABLED

boolean

default:"false"

Enable SCIM 2.0 provisioning for enterprise IdP integration.

LOOM_SERVER_SCIM_TOKEN

string

SCIM bearer token shared with your IdP (e.g., Okta).Generate with: openssl rand -base64 32

LOOM_SERVER_SCIM_ORG_ID

string

UUID of the organization to provision users into.

Weaver Secrets System

LOOM_SECRETS_MASTER_KEY_FILE

string

Path to file containing master encryption key (256-bit, base64-encoded).Generate with: openssl rand -base64 32 > /run/secrets/loom-master-key

LOOM_SECRETS_SVID_SIGNING_KEY_FILE

string

Path to file containing SVID signing key (Ed25519 PEM). Auto-generated if not set.Generate with: openssl genpkey -algorithm Ed25519 -out /run/secrets/svid-signing-key.pem

LOOM_SECRETS_SVID_TTL_SECONDS

integer

default:"900"

TTL in seconds for issued SVID tokens (15 minutes).

LOOM_SECRETS_VERIFY_POD_EXISTS

boolean

default:"true"

Verify weaver Pods exist in Kubernetes before issuing SVIDs.

GeoIP Lookup

LOOM_SERVER_GEOIP_DATABASE_PATH

string

default:"/var/lib/GeoIP/GeoLite2-City.mmdb"

Path to MaxMind GeoIP database file.

Logging

RUST_LOG

string

default:"info"

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

Structured Logging

Loom uses structured logging with automatic secret redaction:

export RUST_LOG=info,loom_server=debug,sqlx=warn

Paths

LOOM_SERVER_DATA_DIR

string

default:"/var/lib/loom"

Base directory for data storage (repos, uploads, etc.).

LOOM_SERVER_BIN_DIR

string

Directory containing CLI binaries for distribution at /bin/{platform}.

LOOM_SERVER_DOCS_INDEX

string

Path to docs-index.json for documentation search.

NixOS Configuration

All environment variables can be set via the NixOS module:

configuration.nix

services.loom-server = {
  enable = true;
  
  # HTTP
  host = "0.0.0.0";
  port = 8080;
  baseUrl = "https://loom.example.com";
  
  # Database
  databasePath = "/var/lib/loom-server/loom.db";
  
  # LLM Providers
  anthropic = {
    enable = true;
    apiKeyFile = "/run/secrets/anthropic-api-key";
    model = "claude-sonnet-4-20250514";
  };
  
  # Weaver
  weaver = {
    enable = true;
    namespace = "loom-weavers";
    imagePullSecrets = [ "ghcr-secret" ];
  };
  
  # SMTP
  smtp = {
    enable = true;
    host = "smtp.example.com";
    port = 587;
    fromAddress = "[email protected]";
    useTLS = true;
  };
};

Validation

The server validates configuration on startup:

Dev mode + production: Fails if LOOM_SERVER_AUTH_DEV_MODE=1 and LOOM_SERVER_ENV=production
Missing secrets: Fails if required API keys are not provided
Invalid paths: Warns if paths don’t exist or aren’t writable

Get Started

Core Features

Architecture

Integrations

Observability

Deployment

​Configuration Sources

​HTTP Server

​Basic Settings

​Example

​Database

​SQLite Options

​LLM Providers

​Anthropic Claude

​OpenAI

​Vertex AI (Google)

​Z.ai (ZhipuAI)

​Authentication

​General Settings

​GitHub OAuth

​Google OAuth

​Okta OAuth (Enterprise SSO)

​Weaver Provisioning

​Audit Sidecar

​SMTP Email

​GitHub App Integration

​Search Providers

​Google Custom Search Engine

​Serper.dev

​Background Jobs

​Git Repository Maintenance

​SCIM Provisioning

​Weaver Secrets System

​GeoIP Lookup

​Logging

​Structured Logging

​Paths

​NixOS Configuration

​Validation

​Next Steps

Server Setup

Database Migrations

Build docs developers (and LLMs) love

Configuration Sources

HTTP Server

Basic Settings

Example

Database

SQLite Options

LLM Providers

Anthropic Claude

OpenAI

Vertex AI (Google)

Z.ai (ZhipuAI)

Authentication

General Settings

GitHub OAuth

Google OAuth

Okta OAuth (Enterprise SSO)

Weaver Provisioning

Audit Sidecar

SMTP Email

GitHub App Integration

Search Providers

Google Custom Search Engine

Serper.dev

Background Jobs

Git Repository Maintenance

SCIM Provisioning

Weaver Secrets System

GeoIP Lookup

Logging

Structured Logging

Paths

NixOS Configuration

Validation

Next Steps