Skip to content
Claude Control Documentation home
InboxAsk a human

Self-hosting an agent with nairid

Self-hosting runs the agent daemon, nairid, on your infrastructure. Nairi's backend still orchestrates events over a WebSocket, but model calls, file edits, branch pushes and pull request creation all happen on your side. That gives you data residency, access to your private network, and capacity outside the concurrency limits. Self-hosted agents are free on every plan.

What you need

  • nairid, via brew install presmihaylov/taps/nairid or built from source with Go 1.24 or newer
  • Git and the GitHub CLI (gh)
  • An AI coding CLI: Claude Code is recommended, Codex and OpenCode also work
  • A Nairi account

macOS, Linux and Windows are supported, on both Intel and ARM.

Setup

Give git an identity, because the agent commits as itself:

git config --global user.name "Nairi Agent"
git config --global user.email "agent@example.com"

Authenticate the GitHub CLI. Use a fine-grained personal access token with read and write on Contents, Pull Requests and Workflows:

gh auth login
gh auth status

Log into your coding CLI, then clone the repository into a directory of its own:

claude          # or: codex login, opencode auth
git clone https://github.com/your-org/your-repo.git
cd your-repo

Set your agent API key and start the daemon:

export NAIRI_API_KEY="your-api-key-here"
export NAIRI_AGENT_ID="my-agent-id"
nairid --agent claude --claude-bypass-permissions

NAIRI_AGENT_ID is required once you run more than one instance.

Read this before using bypass mode

Secure mode is the default. It auto-approves file edits but asks permission for shell commands, which you configure in a config file.

Bypass mode, --claude-bypass-permissions, runs every tool without asking. With it enabled, anyone who can post in your Slack workspace or Discord server can run arbitrary commands on that host as your user. Run nairid in Docker, a VM, or under a dedicated account, never as yourself on your own laptop.

Persistence

Mount a persistent volume at $HOME. Without one, a restart loses state and in-flight jobs are abandoned silently.

Troubleshooting

  • Namespace already locked: another instance is running with the same NAIRI_AGENT_ID.
  • Git errors: check gh auth status and git ls-remote.
  • Stale heartbeat: check that NAIRI_API_KEY is still valid and that a firewall is not blocking the WebSocket.
  • Branches colliding: use a dedicated clone rather than the directory you work in.
  • Endless permission prompts: that is secure mode doing its job. Configure the allowed commands, or move to an isolated host and use bypass.

Several repositories at once

Start in no-repo mode from a working directory, create a repos/ folder with your clones inside it, and start with NAIRI_AGENT_ID=multi-repo-bot. The agent can then work across all of them.