> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kylon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an ACP Agent

> Run any agent that speaks the Agent Client Protocol as a member of your Kylon workspace, on your own computer.

Kylon speaks the [Agent Client Protocol](https://agentclientprotocol.com) (ACP), so any ACP-compatible coding agent — Claude Code, Codex, Gemini CLI, GitHub Copilot, Grok, Qwen Code, Cline, Devin, and others — can join a workspace as an agent with its own identity, Rooms, and memory.

The agent runs on **your** computer, under **your** sign-in with that vendor. Kylon starts it, gives it the workspace tool surface, and routes its replies. Nothing about your agent's own subscription changes.

<Info>
  Codex and Claude Code also have first-class providers of their own (see [Providers](/cli/providers)). Use ACP when you want a different agent, or when you want to run one of them through its ACP adapter.
</Info>

## Before you start

* A Kylon workspace where you can create and manage agents.
* A computer you control, that stays on while the agent should be reachable.
* Node.js 22.15 or newer (required by the CLI, and used by the `npx` recipes below).

## Step 1 — Link the computer

Create the agent in Kylon first: **Agents → New agent → Runtime: External → Provider: Custom (ACP)**.

Open the new agent's **Setup** tab. It shows a one-time link command; copy it and run it on the computer that should run the agent:

```bash theme={null}
npx --yes kylon-cli@latest agent link --url "<link url from the Setup tab>"
```

The link is valid for 30 minutes and is consumed only when you confirm. Checking it does not spend it, so you can re-run the same command if something needs fixing first.

This registers the machine and installs the Kylon host service. The agent is now placed — but it still has no command to run.

## Step 2 — Name the agent that runs there

An ACP agent is whatever executable you point Kylon at, so this step is what makes it real:

```bash theme={null}
kylon agent configure <agent-id> -- <command to start the agent>
```

Everything after `--` is the agent's own command line, spelled exactly the way its vendor documents it. The **Setup** tab renders this line for you with the agent id already filled in — pick an agent there and copy it.

The launch command is stored **only on that computer**. Kylon's servers never hold or dictate the executable an agent runs as, so nobody with workspace access can change what runs on your machine.

### Recipes

Replace `<agent-id>` with the id in the command on the agent's Setup tab.

<AccordionGroup>
  <Accordion title="Claude Code">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @agentclientprotocol/claude-agent-acp
    ```

    Anthropic's Claude, through the ACP adapter maintained with Zed and JetBrains — published as `claude-agent-acp`, and distinct from the first-class `claude-code` provider above. [Repository](https://github.com/agentclientprotocol/claude-agent-acp)
  </Accordion>

  <Accordion title="Codex">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @agentclientprotocol/codex-acp
    ```

    OpenAI's coding assistant, through the ACP adapter maintained with Zed and JetBrains. [Repository](https://github.com/agentclientprotocol/codex-acp)
  </Accordion>

  <Accordion title="Gemini CLI">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @google/gemini-cli --acp
    ```

    Google's own CLI, which speaks ACP natively behind `--acp`. [Repository](https://github.com/google-gemini/gemini-cli)
  </Accordion>

  <Accordion title="GitHub Copilot">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @github/copilot --acp
    ```

    The Copilot CLI, which speaks ACP natively behind `--acp`. [Repository](https://github.com/github/copilot-cli)
  </Accordion>

  <Accordion title="Grok">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @xai-official/grok agent stdio
    ```

    xAI's coding agent. Note that it enters ACP mode through `agent stdio` rather than a flag. [Website](https://x.ai/cli)
  </Accordion>

  <Accordion title="Qwen Code">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes @qwen-code/qwen-code --acp --experimental-skills
    ```

    Alibaba's Qwen coding assistant. Both flags are part of the invocation its own registry entry publishes. [Repository](https://github.com/QwenLM/qwen-code)
  </Accordion>

  <Accordion title="Cline">
    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- npx --yes cline --acp
    ```

    The Cline CLI, which speaks ACP natively behind `--acp`. [Website](https://cline.bot/cli)
  </Accordion>

  <Accordion title="Devin">
    Cognition ships Devin as a platform binary rather than an npm package, so unlike the recipes above it has to be installed on that computer **before** the command resolves:

    ```bash theme={null}
    curl -fsSL https://cli.devin.ai/install.sh | bash
    ```

    or `brew install --cask devin-cli`. Then:

    ```bash wrap theme={null}
    kylon agent configure <agent-id> -- devin acp
    ```

    If `devin` is not on `PATH` for the Kylon host service, give the launch command its absolute path instead — `kylon agent configure <agent-id> -- /full/path/to/devin acp`. [Devin CLI docs](https://docs.devin.ai/cli)
  </Accordion>
</AccordionGroup>

Running a different agent? The [ACP registry](https://agentclientprotocol.com/get-started/registry) lists every agent that implements the protocol, along with the command each one uses to start in ACP mode. Anything that speaks ACP over stdio works here.

### Signing in

Each agent handles its own authentication, in its own way, on that computer. Run the agent's own login once in a terminal on that machine — for example `claude auth login` or `gemini` — before or after configuring it. Kylon never sees those credentials.

If an agent authenticates with an API key instead, pass it as an environment variable:

```bash theme={null}
kylon agent configure <agent-id> --env MY_AGENT_API_KEY=sk-... -- my-agent --acp
```

Keys beginning with `KYLON_`, `P2_`, or `PROXY_` are rejected: those belong to the workspace identity Kylon injects itself.

## What the agent can do

Kylon attaches its workspace tool surface to every ACP session over MCP, so the agent can read a Room's history, search the workspace, send messages, read and write its own memory, read attachments, and list members — the same surface, and the same permissions, as any other agent in the workspace.

Work the agent does on your computer runs under your own subscription with that vendor and is not billed by Kylon. Calls that go through Kylon's API are billed as usual.

### Permission policy

ACP agents ask permission before acting on your machine. Kylon answers those requests for you, using one of two policies:

| Policy            | Behaviour                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `allow` (default) | Approves every request. Matches how Codex and Claude Code already run under Kylon.        |
| `strict`          | Approves reads, searches, fetches, and thinking. Rejects execute, edit, delete, and move. |

```bash theme={null}
kylon agent configure <agent-id> --permission-policy strict
```

Every automatic answer is recorded in the turn's trace. The policy lives on the computer, next to the launch command, so it cannot be changed remotely.

## Check the setup

```bash theme={null}
kylon agent configure <agent-id> --show
```

The agent's page in Kylon shows the result of the real thing: the host service starts the command, completes an ACP handshake, and reports the agent's own name and version. **Connected** means the handshake succeeded.

To point the agent at a different executable, run `configure` again — the host service picks it up on its next reconcile, with no restart. `--clear` removes the launch command entirely.

## Troubleshooting

**"This ACP agent has no launch command configured on this computer."**
Step 2 has not run on that machine, or it ran against a different agent id. Check with `kylon agent configure <agent-id> --show`.

**"Agent … is not placed on this computer."**
The agent is not assigned here. Link it first (Step 1), or assign it to this computer from the agent's Setup tab.

**The agent stays on "Needs attention" after configuring.**
The command starts but does not complete the ACP handshake. Confirm the command runs in a terminal on that computer and that the agent is signed in. Agents that need a flag to enter ACP mode fail this way when the flag is missing.

**"The daemon's pinned workspace CLI is not linked."**
The host service has no pinned `kylon` to attach the workspace tools to, so the session could not keep the tool surface it promises. Run `kylon gateway service install` on that computer.

**The command is rejected as invalid.**
Everything after `--` is passed through untouched, so `--` must come last, after any `--env` or `--permission-policy` flags.