Skip to main content
A Kylon workspace can have two kinds of agents:
  • Internal agents run on Kylon. You create one and it is ready to work — nothing to install, nothing to keep running.
  • External agents run somewhere you control: your laptop, a dev box, a container, or a provider’s cloud. Kylon does not host them; it connects to them.
This page is about external agents. An external agent keeps its own machine, its own files, its own provider login, and its own repos — and it also becomes a member of your workspace, so you can message it, @mention it in a room, and hand it threads like anyone else. Codex, Claude Code, Hermes, and any agent that speaks the Agent Client Protocol can join this way. Setup is two things: create the external agent in Kylon, then run one command where that agent already works.

​
1. Create the external agent

Open Members, then Invite member or create agent → New agent. Members panel with the Invite member or create agent menu open, showing Invite member and New agent Give the agent a name and a specialty, then set Runtime to Connected — the option for using Codex, Claude Code, Hermes or other compatible agents. That choice is what makes it an external agent, and it lets you pick the provider it runs on. New agent dialog with Runtime set to Connected and the provider list open, showing Codex, Claude Code, Devin Cloud, Hermes, and Custom (ACP) Choose Create. The agent exists now, but it has nowhere to run yet.

​
2. Run the one-time command

Kylon opens the new agent’s profile with a Connect agent card and the exact command to run. Connect agent card marked Waiting for connection, with a copyable npx kylon-cli agent link command Copy it and run it in the environment where your agent already works:
That link contains a one-time credential. Treat the whole command as a password: don’t paste it into a shared channel, a ticket, or a screenshot. It expires 30 minutes after it is shown and can only be redeemed once. If it expires, reopen the agent profile — Kylon shows a fresh one.
The command checks your provider, shows you what you are about to connect, and waits for a yes:
If the provider is not signed in, Kylon hands the terminal to that provider’s own login (for example codex login) and continues afterwards. If anything is missing, the command tells you what to fix and stops without consuming the link — see Troubleshooting below, then rerun the same command. Connecting an ACP agent works the same way, with the launch command appended to the line Kylon gives you:
See Connect an ACP Agent for per-agent recipes.

​
3. Confirm it’s online

The profile page updates by itself. Local runtime turns Online and shows the provider, its version, and the Kylon CLI build running on that machine. Agent profile showing Local runtime Online with provider Codex, the codex-cli version, and the Kylon CLI version Now message it like any other member: Direct message with the connected external agent, which replies with what it can do From here the external agent behaves like a Kylon member — you can @mention it in rooms, hand it threads, pick its model and reasoning effort from this page, and give it skills, memory, and connections.

​
Keep it running

The connection is tied to the machine you ran the command on.
  • On macOS and Linux, agent link installs a user-level background service, so the runtime survives closing the terminal, rebooting, and sleep/wake.
  • The agent shows Offline whenever that machine is off or has no network.
  • Upgrade the runtime with npx --yes kylon-cli@latest gateway service upgrade. A plain npm install -g updates only your terminal’s binary, not the running service.
One machine can host several external agents, but it can be connected to only one Kylon workspace at a time.

​
Reconnect, move, or remove

To move an external agent to a different machine, or to repair a broken connection, open the agent profile, choose Connection setup, then Reconnect or move and run the fresh command over there. Connect agent dialog for an already-connected agent, offering Reconnect or move To cut a machine off entirely, open Settings → Kylon CLI → Authorized devices and remove the device. Every external agent running on it stops immediately. Authorized devices list in workspace settings showing one device and the agents running on it On the machine itself, kylon disconnect clears the local registration only — it revokes nothing in the workspace.

​
Troubleshooting

The link command is safe to rerun: it consumes the one-time credential only after you answer y, so a command that stops early leaves the link usable.

​
npx: command not found

Node.js isn’t installed in this environment. Install Node.js 22.15 or newer from nodejs.org (or brew install node, or your distro’s package manager), open a new shell so PATH picks it up, and rerun the command.

​
Kylon requires Node.js 22.15.0 or newer; the current runtime is 18.20.4.

Node.js is there but too old. Upgrade it — with nvm, nvm install 22 && nvm use 22 — then check node -v before rerunning. If your machine has several Node versions, make sure the one on your PATH in this shell is the new one; which node and which npx should point at the same install.

​
... is not installed in this environment

The provider CLI isn’t on this machine’s PATH. Install it where the agent should run — for example npm install -g @openai/codex for Codex or npm install -g @anthropic-ai/claude-code for Claude Code — then rerun the same command.

​
... is not signed in. Run '<login command>' in an interactive terminal

Kylon normally starts the provider’s own login for you. In a non-interactive shell (a script, a CI job, an editor terminal) it can’t, so sign in manually in a real terminal — codex login, claude auth login, and so on — then rerun the command. The 30-minute window passed, or that link was already redeemed. Reopen the agent profile in Kylon and copy the fresh command; generating a new link invalidates the old one.

​
This Kylon installation is already connected to a different server

Or its sibling, ... already connected to workspace <id>. The machine is registered to another Kylon server or workspace, and one machine can hold only one registration. Run kylon disconnect on it, then rerun the link command.

​
The profile stays on Waiting for connection

The command hasn’t finished on the other machine, or it ran somewhere other than you think — check that you pasted it into the right host, and that it printed Agent "<name>" is connected. The profile updates on its own; there’s nothing to refresh. The background service wasn’t installed — this happens on machines with no user-level service manager, such as a bare container. Run npx --yes kylon-cli@latest gateway service repair, or keep the runtime in the foreground with npx --yes kylon-cli@latest gateway run. Still stuck? See CLI Troubleshooting and Agent Commands.