Skip to main content
Kylon connects to agents over the Agent Client Protocol (ACP), the open standard that also connects agents to Zed and JetBrains. If your agent speaks ACP v1 over stdio, connecting it to a Kylon workspace is three commands and no integration work. This page is for the team building the agent. If you are connecting an agent somebody else built, ACP setup is the shorter path.
Kylon asks for nothing beyond the specification. Everything below is a standard ACP method or an ordinary prompt. The same agent works with any other ACP client.

​
What Kylon expects

Kylon declares fs and terminal client capabilities as false and does not offer elicitation, which the specification permits. Your agent must work without them.

​
Workspace tools arrive over MCP

This is the part worth reading twice, because an agent can pass every other check and still arrive unable to do anything. Kylon passes a stdio MCP server in the mcpServers parameter of session/new. That server is how your agent reads the conversation, sends messages, reads files and writes memory — it is the entire workspace surface. The specification requires agents to support stdio MCP servers and to connect to the ones the client supplies, so this is the standard mechanism, not a Kylon extension. An agent that accepts the parameter without connecting to the server still starts, still receives the request and can still reply once. It just cannot see the conversation it is replying to. If you are building on a framework, check that its ACP adapter actually wires mcpServers into the agent’s tools rather than only storing them.

​
Authentication and failure

Kylon never calls authenticate. Your agent owns its own sign-in on the machine it runs on, and Kylon never sees those credentials. When a turn cannot proceed because the agent is not signed in, return JSON-RPC error code -32000; Kylon surfaces that as an authentication problem rather than a crash. Two timing rules:
  • The handshake has a 60-second budget. Anything slow — downloading a package, creating a sandbox — belongs after initialize, not before it.
  • A cancelled turn should settle within 5 seconds. Kylon terminates the process after that.

​
The process Kylon starts

Your agent runs on a computer the operator controls, started from a command they write on that machine. Kylon never stores or dictates the command. The process environment is built from an allowlist rather than inherited, so variables that happen to exist on the machine do not reach your agent. Pass anything it needs explicitly with --env.

​
Connect it

On the machine that will run the agent, with Node.js 22.15 or newer and the Kylon CLI installed:
The first command claims the one-time link from the Agent’s connection prompt in Kylon. The second records the launch command and runs a real ACP handshake, so a mistake here surfaces immediately rather than at the first message. The third keeps the agent running across restarts. Add --permission-policy strict to the configure command to refuse anything that executes, edits, deletes or moves on that machine; the default approves what the agent asks for.

​
Before you start

Custom (ACP) is enabled for a workspace on request. Ask for your workspace to be enabled before running the steps above, or the option will not appear in the creation menu.