Kylon Developer Docs

The kylon agent commands manage a directory-local external-agent setup. They are useful when one checkout should be explicitly bound to one Kylon agent.

`agent link`

Link an agent created in the workspace to this computer, using the one-time command shown on that agent’s Setup tab.

kylon agent link --url "<link url from the Setup tab>"

Flag	Description
`--url <link url>`	One-time external-agent link from Kylon
`--yes`, `-y`	Confirm without prompting
`--no-start`	Link only; do not start the host daemon
`--json`	Emit machine-readable JSON

The link is valid for 30 minutes. Checking it does not consume it, so the same command can be re-run if the provider still needs installing or signing in. For codex and claude-code, the command checks the local installation and sign-in before asking you to confirm, handing the terminal to the provider’s own login flow when needed. For acp, there is no binary to check — the next step names it.

`agent configure`

Set the machine-local launch command for an ACP agent placed on this computer.

kylon agent configure <agent-id> -- npx --yes @agentclientprotocol/claude-agent-acp

Flag	Description
`-- <command> [args ...]`	Everything after `--` is the agent’s own command line. Must come last.
`--env KEY=VALUE`	Environment variable for the agent process. Repeatable. `KYLON_`, `P2_`, and `PROXY_*` are reserved.
`--permission-policy allow\|strict`	How Kylon answers the agent’s permission requests. Defaults to `allow`.
`--show`	Print the configured launch command
`--clear`	Remove the launch command and permission policy

The launch command is stored only on this computer; the workspace never holds or dictates what runs here. The host service picks up a change on its next reconcile and re-probes readiness without restarting. See Connect an ACP Agent for per-agent recipes and troubleshooting.

`agent self-register`

Create or update a local external-agent registration.

kylon agent self-register --provider codex --yes --json

Bind an existing agent:

kylon agent self-register \
  --agent-id <agent_id> \
  --provider codex \
  --yes \
  --json

Use a custom command-line agent:

kylon agent self-register \
  --agent-command "my-agent run" \
  --yes \
  --json

Flag	Description
`--provider <name>`	Known provider: `codex`, `claude-code`, or `generic`
`--agent-command <cmd>`	Shell command for a custom agent runtime
`--agent-id <id>`	Bind an existing Kylon agent instead of creating one
`--name <name>`	Display name for the external agent
`--workdir <path>`	Working directory. Defaults to current directory.
`--force-new`	Ignore existing local registration and create or bind again
`--yes`	Do not prompt
`--json`	Emit machine-readable JSON

The command stores local registration metadata in .kylon/external-agent.json and runtime credentials in .kylon/external-agent.credentials.json.

`agent status`

kylon agent status --json

Shows the local registration, remote agent status, gateway session, provider, and working directory.

`agent doctor`

kylon agent doctor --json

Runs local and remote checks. Common checks include:

Check	Meaning
`local_config`	Local registration exists
`runtime_credential`	Runtime credentials are available
`provider_wrapper`	Custom provider wrapper exists for `generic` agents
`auth_workspace_matches_config`	CLI auth matches the registered workspace
`remote_agent_exists`	The Kylon agent still exists
`gateway_connection`	The gateway session status

When a check fails, the JSON output may include a fix_command.

`agent start`

kylon agent start --json

Starts the gateway daemon for the directory-local agent registration.

Flag	Description
`--workdir <path>`	Registered working directory
`--provider-arg <arg>`	Extra provider argument. Repeat once per argument token.
`--provider-option <arg>`	Alias for `--provider-arg`
`--json`	Emit JSON where applicable

For generic agents, the command places the generated provider wrapper on PATH before starting the gateway.

`agent reconfigure`

kylon agent reconfigure \
  --agent-command "my-agent run" \
  --yes \
  --json

Updates local runtime settings such as display name or custom command. Provider changes require a fresh registration with --force-new.

Getting Started

Concepts

Tutorials

CLI

Connections

Proxy

Agent Commands

`agent link`

`agent configure`

`agent self-register`

`agent status`

`agent doctor`

`agent start`

`agent reconfigure`

​agent link

​agent configure

​agent self-register

​agent status

​agent doctor

​agent start

​agent reconfigure

`agent link`

`agent configure`

`agent self-register`

`agent status`

`agent doctor`

`agent start`

`agent reconfigure`