On this page

Loom

Configuration

Loom is configured through a YAML file (loom.yml) with environment-variable overrides layered on top. The resolution order is:

  1. Load loom.yml from the first location that exists (see below), or fall back to built-in defaults.

  2. Apply environment variables — any LOOM_* variable overrides the corresponding YAML value.

  3. Validate the result (e.g. a keystore password must be present; one is generated if unset).

So for container deployments you can skip the file entirely and configure everything with environment variables.

Config File Locations

Loom looks for loom.yml in the following order (first match wins):

  1. /etc/metaloom/loom.yml — system-wide config

  2. ~/.config/metaloom/loom.yml — user home config

  3. config/loom.yml — relative to the working directory

If none exist (and none is on the classpath), Loom writes a default config/loom.yml on first start.

Full Configuration Example

Every top-level key maps to an options group. Only the keys you want to change need to be present.

database:
  host: "127.0.0.1"
  port: 5432
  username: "postgres"
  password: "finger"
  databaseName: "loom"
  minPoolSize: 5
  acquireIncrement: 5
  maxPoolSize: 20

server:
  restPort: 8092          # REST API + WebSocket + UI
  grpcPort: 8091          # gRPC
  monitoringPort: 8989    # health / metrics
  mcpPort: 4041           # Model Context Protocol server
  bindAddress: "0.0.0.0"

auth:
  keystorePath: "keystore.jceks"
  keystorePassword: "change-me"   # generated if omitted
  tokenExpirationTime: 3600
  oauth2:
    enabled: false
    # clientId / clientSecret / authUrl / tokenUrl / userInfoUrl / callbackUrl / logoutUrl / scope

storage:
  uploadDirectory: "data/storage"   # where uploaded asset binaries are stored

ai:                       # Chat & AI agent — see the "AI Agent" section below
  enabled: true
  providerType: "OLLAMA"
  url: "http://127.0.0.1:11434"
  modelId: "gpt-oss:20b"

sandbox:                  # Agentic coding sandbox — off by default
  enabled: false
  backend: "podman"

memory:                   # Agent memory bank — off by default
  enabled: false

Environment Variables

All settings can be overridden with environment variables. Environment variables take precedence over values in loom.yml.

Database

Variable Default Description

LOOM_DB_HOST

127.0.0.1

PostgreSQL host

LOOM_DB_PORT

5432

PostgreSQL port

LOOM_DB_USERNAME

postgres

Database username

LOOM_DB_PASSWORD

finger

Database password

LOOM_DB_NAME

loom

Database name

LOOM_DB_MIN_POOL_SIZE

5

Minimum connection pool size

LOOM_DB_MAX_POOL_SIZE

20

Maximum connection pool size

Server

Variable Default Description

LOOM_SERVER_REST_PORT

8092

HTTP REST port (REST + WebSocket + UI)

LOOM_SERVER_GRPC_PORT

8091

gRPC port

LOOM_SERVER_MCP_PORT

4041

Model Context Protocol server port

LOOM_SERVER_GRPC_BIND_ADDRESS

0.0.0.0

Bind address for all listeners

LOOM_SERVER_MON_PORT

8989

Monitoring/health port

Storage

Variable Default Description

LOOM_STORAGE_UPLOAD_DIR

data/storage

Directory where uploaded asset binaries are stored

Near-duplicate video lookup

Powers "which other videos look like this one?", and with it the near-duplicate review workflow of the deduplication nodes. It is switched off by default because it is only useful once videos have been fingerprinted.

The lookup keeps its own index on disk. That index is built entirely from fingerprints already stored with your assets, so it can be discarded and rebuilt at any time without data loss.

Variable Default Description

LOOM_SIMILARITY_ENABLED

false

Enable near-duplicate lookup. While off, requests to the similar-videos routes are refused with a clear reason rather than answering "nothing found"

LOOM_SIMILARITY_INDEX_PATH

similarity-index

Directory holding the lookup index. Give each server its own directory — two servers cannot share one

LOOM_SIMILARITY_ALGORITHM

metaloom-multisector-v1

Which fingerprint version takes part in the lookup

LOOM_SIMILARITY_SCORE_THRESHOLD

0.10

How close a match must be to count as a near-duplicate. Higher is stricter

LOOM_SIMILARITY_TOPK

10

How many similar videos a query returns by default
Note
 If the index directory cannot be written, the server still starts normally — only the near-duplicate routes report themselves as unavailable.

Authentication

Variable Default Description

LOOM_INITIAL_PASSWORD

(random)

Initial admin password (first boot only)

LOOM_TOKEN_EXPIRATION_TIME

3600

JWT token lifetime in seconds

LOOM_MCP_AUTH_ENABLED

false

Require auth on the MCP endpoints

LOOM_MCP_AUTH_STRICT_MODE

false

Reject unauthenticated MCP calls (no lenient mode)

LOOM_MCP_AUTH_ALLOWED_ORIGINS

*

CORS origins allowed on the MCP SSE endpoint

The keystore password is read from the auth.keystorePassword config key (a random one is generated if unset). See Authentication.

OAuth2

Optional OAuth2 login (BFF pattern). Set LOOM_OAUTH2_ENABLED=true and provide your provider’s endpoints:

Variable Description

LOOM_OAUTH2_ENABLED

Enable OAuth2 authentication (default false)

LOOM_OAUTH2_CLIENT_ID / LOOM_OAUTH2_CLIENT_SECRET

Client credentials

LOOM_OAUTH2_AUTH_URL / LOOM_OAUTH2_TOKEN_URL / LOOM_OAUTH2_USERINFO_URL

Provider endpoints

LOOM_OAUTH2_CALLBACK_URL / LOOM_OAUTH2_LOGOUT_URL

Callback and logout URLs

LOOM_OAUTH2_SCOPE

Scopes to request (default openid profile email)

AI Agent

Settings for the built-in Chat & AI Agent. The agent is enabled by default (LOOM_AI_ENABLED=true) but needs a reachable LLM provider to answer.

Variable Default Description

LOOM_AI_ENABLED

true

Master switch for the chat agent

LOOM_AI_PROVIDER_TYPE

OLLAMA

LLM provider (OLLAMA | VLLM)

LOOM_AI_URL

http://127.0.0.1:11434

Provider base URL

LOOM_AI_MODEL_ID

gpt-oss:20b

Model id

LOOM_AI_CONTEXT_WINDOW

16384

Context window (tokens)

LOOM_AI_MAX_TURNS

8

Max tool-calling turns per message

LOOM_AI_TOOL_TIMEOUT_MS

30000

Per-tool timeout

LOOM_AI_STREAMING

false

Opt-in true token/reasoning streaming

LOOM_AI_THINK_ENABLED

(model default)

Enable model "thinking" chunks

LOOM_AI_TITLE_GENERATION

(on)

Auto-title a chat after the first exchange

Coding Sandbox

Settings for the per-chat coding sandbox (LOOM_AGENT_SANDBOX_*). Off unless LOOM_AGENT_SANDBOX_ENABLED=true. See Chat & AI Agent — Coding Sandbox for the full table and deployment (backends, Kubernetes RBAC, the runner image). Key switches: LOOM_AGENT_SANDBOX_BACKEND (podman \| kubernetes), LOOM_AGENT_SANDBOX_IMAGE, LOOM_AGENT_SANDBOX_NAMESPACE, LOOM_AGENT_SANDBOX_IDLE_TTL_S, LOOM_AGENT_SANDBOX_MAX_SESSION_S, LOOM_AGENT_SANDBOX_MAX_CONCURRENT.

Agent Memory

Settings for the agent memory bank (LOOM_AGENT_MEMORY_*):

Variable Default Description

LOOM_AGENT_MEMORY_ENABLED

false

Enable the memory bank

LOOM_AGENT_MEMORY_MAX_ENTRIES_PER_SCOPE

(quota)

Max notes per scope

LOOM_AGENT_MEMORY_MAX_ENTRY_BYTES

(quota)

Max size of a single note

LOOM_AGENT_MEMORY_MAX_SCOPE_BYTES

(quota)

Max total size per scope

LOOM_AGENT_MEMORY_MAX_WRITES_PER_RUN

(quota)

Max memory writes per agent run

LOOM_AGENT_MEMORY_SHARED_SCOPES_ENABLED

false

Allow shared (cross-user) scopes

LOOM_AGENT_MEMORY_MOUNT_ENABLED

false

Mount memory read-only into the coding sandbox

LOOM_AGENT_MEMORY_MOUNT_PATH

/memory

Sandbox mount path for memory

CLI

The Loom server main entry point is LoomServerRunner. Configuration is driven via the YAML file and environment variables shown above.

The metaloom command-line client is a separate program that talks to a running Loom server over the REST API and has its own configuration file.

Looking for something else?

All documentation Feature overview