Gleipnir

Gleipnir is a self-hosted runner for AI agents that quietly handle work you'd rather offload, built so you can leave them running and not worry about what they're doing.

What you can do with it

• Plan the week's meals. Checks your calendar for nights without dinner plans, picks recipes from Mealie for the empty slots, and schedules them in your meal plan. → Playbook
• Research your own todo list. Finds Todoist tasks tagged AI_Assist, gathers context with web search, and posts the findings as a comment on each task. → Playbook
• Run homelab DevOps from natural language. Restart Docker containers, fix Proxmox VMs, update Technitium DNS records, or reconfigure Caddy routes — every write is approval-gated. → Playbook
• Drive a Linux fleet through Relay. Ask the fleet questions in plain language and get typed, read-only Operations back. Let an Uptime Kuma alert propose a scoped restart, which Relay puts to a human in Gleipnir before anything changes. The agent is never given raw shell access. → Playbook

How it stays safe

Every Gleipnir agent runs against an explicit list of tools you grant it. Tools that aren't on the list are never registered with the agent, so they don't exist from its perspective. There is no prompt-based restriction to bypass and no clever phrasing that unlocks something you didn't allow.

Any tool can be marked as requiring approval. When the agent tries to use one, the run pauses, you get a request in the UI showing exactly what the agent wants to do, and nothing happens until you approve or reject it. Every step the agent takes — its thoughts, its tool calls, the results, the approvals — is recorded in a reasoning trace you can read after the fact.

Quick start

Option A — pre-built image (no clone required):

docker pull felagengineering/gleipnir:latest

Create a docker-compose.yml and a .env file as shown in Setup, then jump to step 3 below.

Option B — build from source:

1. Clone the repo and copy the environment template:

   git clone https://github.com/Felag-Engineering/gleipnir.git
   cd gleipnir
   cp .env.example .env

2. Generate an encryption key and add it to .env:

   openssl rand -hex 32
   # Paste the output into GLEIPNIR_ENCRYPTION_KEY in .env

3. Start the stack:

   docker compose up -d

4. Open http://localhost:8080 in your browser.

5. Complete the first-run setup: create the admin user, then add your LLM provider API key at Admin → Models.

Back up your encryption key

GLEIPNIR_ENCRYPTION_KEY is a mandatory AES-256 key that encrypts every provider API key and webhook secret stored in the database. Losing it makes those credentials permanently unrecoverable — there is no fallback decryption path. Store it in a password manager or secrets vault immediately after generating it. See Operations — Backing up the encryption key.

Your first agent

Once the stack is running and you're logged in, here's how to wire up your first agent:

1. Go to Tools (/tools) and click Add MCP server. Give it a name and the URL of any MCP server you have running.
2. Click Discover on the new server. Gleipnir reads the server's tool list and shows them in the UI. Disable any tool you don't want any agent to use — the kill switch on the Tools page is server-wide.
3. Go to Agents → New Agent (/agents/new). Pick a webhook (or manual) trigger, write a short task description for the agent, and grant the tools you want the agent to use. Mark any write/destructive tool as requiring approval — this gates that tool behind operator review at runtime.
4. Click Run now on the new agent to fire a manual run.
5. Open the run from the Run History list and watch the trace populate as the agent works.

For fully worked examples against specific services, follow one of the playbooks.

Plugins

Gleipnir supports plugins — signed sandboxed subprocesses that add tools, notification channels, and trigger event sources. Drop a .tar.gz bundle into GLEIPNIR_PLUGINS_DIR (default: /plugins) or upload it via Admin → Plugins. Signed plugins require admin approval before any subprocess is spawned. Signature verification and TOFU key pinning are enforced by default; every signing key is pinned on first install and subsequent updates must match.

See Plugins for the full operator runbook: installing, signing, approving, and rotating keys.

More reading

• Setup — detailed first-run walkthrough.
• Policies — trigger types, capability grants, run states.
• Roles — what each role can and cannot do.
• Plugins — installing, signing, approving, and key-rotating plugins.
• Operations — upgrading, backups, environment variables.
• Playbooks — copy-pasteable setups for the use cases above.
• Developer docs — architecture, building, contributing.
• CLI commands — gleipnirctl local admin CLI (e.g. rotate-key for encryption key rotation).
• Security notes

License

Business Source License 1.1. Non-production use is free; production use requires a commercial license from Felag Engineering until the Change Date (2028-04-21), after which this version converts to Apache License 2.0.