Docs · Get started

Agent harnesses

Install the harnesses your agents work through from the Terminal: Claude Code, Codex, Hermes Agent, pi, Gemini CLI, OpenCode and Kimi Code.

KyoubeAI 1.11.0 · · Source on GitHub (opens in a new tab)

Agents work through an agent harness: Claude Code, Codex, Hermes Agent, pi, Gemini CLI, OpenCode or Kimi Code. You install the ones you want from the Terminal (the Workspace page, then Terminal, for company owners and admins), the same way you would on your own machine.

What you install stays:

  • Harnesses land in /kyoubeai/.local, on the kyoubeai-home volume, which comes first on the PATH of every agent and every Terminal shell.
  • Their logins (~/.claude, ~/.codex, ~/.hermes, ~/.pi, and so on) live on the same volume.
  • System packages you add with sudo apt install are put back automatically after a restart, an update or a core upgrade.

All of it survives docker compose down, ./update.sh and core upgrades, and scripts/backup.sh carries it to a new machine. The Terminal runs as the same user as your agents and has sudo, so treat Terminal access as root on the container (SECURITY.md).

kyoube harness install claude   # also: codex, hermes, pi, gemini, opencode, kimi
kyoube harness list             # what is installed, which version, and whether it is yours

kyoube harness install runs the harness's official installer. The core image carries its own copies of Claude Code, Codex, Gemini CLI, Kimi Code and OpenCode as fallbacks; yours take precedence. kyoube doctor flags any harness your agents use that is not installed or no longer runs. KyoubeAI has no installer for Grok: install it from its own instructions so that grok lands in /kyoubeai/.local/bin.

How agents reach a model

  • AI connections hold a subscription sign-in or an API key centrally, and hand it to each run. You add one from an agent's Runtime tab, under AI connection. Claude Code, Codex, OpenCode and Grok can use them.
  • The harness's own login, made in the Terminal, or provider keys in .env (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY; docker compose up -d applies them). pi and Hermes always work this way; the others do for agents that have no AI connection.

Claude Code

  1. kyoube harness install claude. This is the official native installer, and it keeps Claude Code up to date.
  2. Connect it, one of these ways:
    • Pro or Max subscription, as an AI connection. On the agent's Runtime tab, choose Claude Code, then add a Claude subscription under AI connection. It shows a command ending in kyoube connect claude. Paste it into the Terminal, sign in at the link it prints, and paste the code back (if it then asks for the token Claude printed, paste that). When the Terminal says Done, click Connect. The connection holds a one-year token; connect it again once a year.
    • Anthropic API key: add it as an AI connection, or set ANTHROPIC_API_KEY in .env.
    • Just your own login: run claude in the Terminal and use /login. Agents without an AI connection use it, and Claude keeps it refreshed.
  3. Choose Claude Code and the connection on the agent's Runtime tab.

Claude subscription connections made before 1.1 hold an 8-hour token and stop working; connect them again once, as above.

Codex

  1. kyoube harness install codex.
  2. Add an OpenAI subscription (the page shows a device sign-in) or an OpenAI API key as an AI connection, or run codex login in the Terminal for agents without one.
  3. Choose Codex on the agent's Runtime tab. Keep Bypass sandbox on: Codex's own sandbox needs kernel features a container does not have, and the container is the sandbox.

Hermes Agent

  1. kyoube harness install hermes.
  2. Run hermes setup in the Terminal to pick a provider and model and enter keys (OpenRouter and others). Its settings, sessions and memory live in ~/.hermes.
  3. Choose Hermes on the agent's Runtime tab. Hermes does not use AI connections.

pi

  1. kyoube harness install pi.
  2. Run pi in the Terminal and use /login, or put provider keys in ~/.pi.
  3. Choose pi on the agent's Runtime tab. pi does not use AI connections.

Gemini CLI, OpenCode, Kimi Code

The core image carries a copy of each. kyoube harness install gemini (or opencode, kimi) installs your own, newer copy, which then takes precedence. Sign in from the Terminal as each one's documentation describes.

Switching an agent's harness

On the Runtime tab, pick the new harness and, in the same save, an AI connection that works with it, or none. The save is refused while the agent still has a connection for another provider. Test works before you save.

After an update or a core upgrade

kyoube doctor lists each installed harness and whether it still starts. One that no longer runs, for example after the core moves to a new Node.js, shows its reinstall command. It also reports the kept system packages, and fails if they could not be put back at the last start.