# Norn documentation

> Documentation for Norn, an open-source, keyboard-first issue tracker for teams and AI agents. Norn is self-hostable under AGPL-3.0 and also runs as a managed cloud hosted only in the EU, with unlimited members and issues, no per-seat pricing, and SAML and OIDC SSO on every tier. These docs cover delegating work to an agent that runs on your own machine, deployment, configuration, single sign-on, the GitHub App, the HTTP API, and the MCP server.

Every documentation page is also served as plain markdown at the same path with a .md suffix.

## Start here

- [Overview](https://docs.norn.so/index.md): an issue tracker you run yourself — where to go for each task

## Delegated work

- [Delegated work](https://docs.norn.so/delegate.md): hand an issue to an agent, run it on a machine you control, and review what comes back
- [Connect a machine](https://docs.norn.so/delegate/connect-a-machine.md): install the Norn Runner and bind it to an agent
- [Connect a folder](https://docs.norn.so/delegate/connect-a-folder.md): point a machine at the repositories work should happen in, and keep the inventory in step
- [Manage machines](https://docs.norn.so/delegate/machines.md): machine states, pausing, and revoking one without disabling its agent
- [Delegate an issue](https://docs.norn.so/delegate/issues.md): hand an issue over, say what you want done, and take it back
- [Watch a run](https://docs.norn.so/delegate/runs.md): the timeline, services, transcript, and answering the questions a run stops to ask
- [Previews](https://docs.norn.so/delegate/previews.md): open what a run is running, and share it with a link that expires
- [Review a run](https://docs.norn.so/delegate/review.md): read the diff across every repository, then approve it or send it back
- [Recipes](https://docs.norn.so/delegate/recipes.md): worked solutions to the situations people hit once the basics are running
- [Run a machine in a container](https://docs.norn.so/delegate/recipes/container.md): connect a runner where there is no service manager and no machine id, and keep it alive across restarts
- [Make an agent plan first](https://docs.norn.so/delegate/recipes/plan-first.md): have a coding agent publish its approach and wait for approval before writing code
- [norn runner reference](https://docs.norn.so/delegate/cli.md): every norn runner command and its flags

## Self-hosting

- [Self-host Norn](https://docs.norn.so/self-hosting.md): choose a supported way to deploy Norn on infrastructure you control
- [Configure Norn](https://docs.norn.so/self-hosting/configuration.md): configuration shared by every self-hosting method
- [Environment variable reference](https://docs.norn.so/self-hosting/environment-variables.md): every Norn setting, its default, and what it controls
- [Install with Docker Compose](https://docs.norn.so/self-hosting/compose.md): install Norn on a single host with the official Docker Compose file
- [Configure the Docker Compose deployment](https://docs.norn.so/self-hosting/compose-configuration.md): secrets, external services, routing, and scaling under Docker Compose
- [Operate a Docker Compose deployment](https://docs.norn.so/self-hosting/compose-operations.md): back up, upgrade, restore, and remove a deployment
- [Troubleshoot a Docker Compose deployment](https://docs.norn.so/self-hosting/compose-troubleshooting.md): diagnose startup, certificates, routing, storage, email, and configuration
- [Install with Helm](https://docs.norn.so/self-hosting/helm.md): install Norn on Kubernetes with the official Helm chart
- [Configure the Helm deployment](https://docs.norn.so/self-hosting/helm-configuration.md): secrets, external services, routing, email, and scaling
- [Operate a Helm deployment](https://docs.norn.so/self-hosting/helm-operations.md): back up, upgrade, restore, and remove a deployment
- [Troubleshoot a Helm deployment](https://docs.norn.so/self-hosting/helm-troubleshooting.md): diagnose migrations, routing, storage, email, and upgrades

## Single sign-on and GitHub

- [Single sign-on](https://docs.norn.so/sso.md): configure OIDC or SAML 2.0, test the connection, and require SSO without locking administrators out
- [Configure the instance GitHub App](https://docs.norn.so/github-app-registration.md): create a GitHub App and configure its credentials on a self-hosted instance
- [Connect GitHub repositories](https://docs.norn.so/github-repositories.md): install the instance GitHub App and connect repositories to a workspace

## API and MCP

- [API and MCP](https://docs.norn.so/api.md): the dashboard API — authentication, error format, resource groups, and the MCP connection surface

## Changelog

- [Changelog](https://docs.norn.so/changelog): releases and notable changes to Norn
- [RSS feed](https://docs.norn.so/changelog/rss.xml): changelog syndication

## Optional

- [Product site](https://norn.so/): product overview, pricing model, and comparison with Linear, Jira, and Plane
- [Product llms.txt](https://norn.so/llms.txt): summary of the product for language models
- [GitHub](https://github.com/usenorn/norn): AGPL-3.0 source code