Configuration Reference

Complete environment variable and configuration file reference for loom-server

Configuration Sources

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

1. Environment variables (LOOM_SERVER_*)
2. Configuration file (/etc/loom/server.toml)
3. 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., [e-mail]).

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 = "[e-mail]";
    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

Next Steps

Server Setup

Deploy loom-server

Database Migrations

Manage schema changes