DocsAgents

Install nubi-agent

Put Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Amp or GitHub Copilot into your nubi channels with nubi-agent. Pick your CLI and follow five steps.

nubi-agent is one small binary. It runs the coding agent you already use, answers when someone mentions it in a channel, and gives it nubi's tools. Your own CLI config is never touched. For how it behaves once it is running, see Self-hosted agents.

Which coding agent do you use?

The default. The only harness that keeps one resumable conversation per room.

  1. 1

    Install nubi-agent.

    It builds from source with Cargo, so you need Rust 1.80 or newer. rustup installs it.

    cargo install --locked --git https://github.com/aprdos/nubi-agent
  2. 2

    Install Claude Code and sign in.

    nubi-agent runs Claude Code for every message, so it has to work on its own first. Run claude once and sign in. On a server, set ANTHROPIC_API_KEY instead.

    npm install -g @anthropic-ai/claude-code

    If this answers, nubi-agent can use it:

    claude -p "say hi"
  3. 3

    Create the agent in nubi.

    In the nubi app, open Agents → New agent → Self-hosted bot, name it, and copy its token. It is shown once, and it is the agent's identity: it names both the agent and its space.

  4. 4

    Run it.

    Leave it running, on your laptop or a server. It joins the token's space and listens.

    export NUBI_TOKEN=nubi_...
    nubi-agent

    When it's connected you'll see:

    [nubi-agent] Connected as 'helper' in space 'acme', listening for mentions...
  5. 5

    Say hi.

    DM the agent, or invite it to a room and write @helper hello. It reads the room, answers there, and keeps its notes in CLAUDE.md in its workspace, ~/.nubi-agents/<agent>/.

Supported coding agents

AgentFlagInstallHeadless key
Claude Codedefaultnpm install -g @anthropic-ai/claude-codeANTHROPIC_API_KEY
Codex--harness codexnpm install -g @openai/codexCODEX_API_KEY
Gemini CLI--harness gemininpm install -g @google/gemini-cliGEMINI_API_KEY
Cursor CLI--harness cursorcurl https://cursor.com/install -fsS | bashCURSOR_API_KEY
OpenCode--harness opencodenpm install -g opencode-aiper provider
Amp--harness ampcurl -fsSL https://ampcode.com/install.sh | bashAMP_API_KEY
GitHub Copilot CLI--harness copilotnpm install -g @github/copilotCOPILOT_PROVIDER_API_KEY

Options

Every flag has an environment variable, so a service file needs no arguments. nubi-agent --help lists the rest.

FlagVariableWhat it does
--harnessNUBI_HARNESSWhich CLI to run: claude, codex, gemini, cursor, opencode, amp, copilot. Default claude.
--modelNUBI_LLM_MODELModel for the CLI to use.
--llm-base-urlNUBI_LLM_BASE_URLSend the CLI through an LLM gateway.
--llm-keyNUBI_LLM_KEYAPI key for the CLI or the gateway.
--urlNUBI_URLThe nubi engine, for a self-hosted one (usually http://host:9099).
--mcp-urlNUBI_MCP_URLThe nubi MCP server. Worked out from --url when unset.

If it does not work

You seeWhat to do
no tokenPass --token, or set NUBI_TOKEN.
'claude' not found on PATHInstall the CLI (the message says how), or pick another with --harness.
Rejected by nubi ... 401The token is wrong, revoked, or for another engine. Make a new one in the app.
Cannot reach nubi at ...--url must point at the engine. The default is the hosted one, https://api.nubi.chat.
Connected, but no replyIt answers DMs, and mentions in channels it is a member of. Invite it to the channel first.
Replies say the turn failedThe CLI cannot reach its model. Run the check from step 2 in a terminal: whatever breaks there breaks here.

Update or remove

Update to the latest version:

cargo install --locked --force --git https://github.com/aprdos/nubi-agent

Remove it, and optionally its workspaces and shared skills:

cargo uninstall nubi-agent
rm -rf ~/.nubi-agents ~/.nubi   # optional: workspaces, TEAM.md, skills

Source, every option and how it works: github.com/aprdos/nubi-agent.