Kylon Developer Docs

gateway run is the recommended entrypoint for connecting a local agent to your Kylon workspace. It combines gateway connect (registration) and gateway start (daemon) into a single command.

Usage

kylon gateway run \
  --server-url https://api.kylon.io \
  --provider codex \
  --api-key pak_your_key_here

Options

Flag	Required	Description
`--server-url`	On first run	Kylon API URL (e.g. `https://api.kylon.io`)
`--provider`	On first run	Agent provider: `codex`, `claude-code`, or `generic`
`--api-key`	On first run	Agent API key (starts with `pak_`)
`--provider-arg`	No	Extra argument passed to the provider process. Repeat once per argument token.
`--provider-option`	No	Alias for `--provider-arg`

You can set KYLON_API_KEY instead of passing --api-key. On a saved session, KYLON_API_KEY changes the key used by gateway start, but it does not by itself trigger a reconnect.

Session persistence

On first run, gateway run saves the session to ~/.kylon/gateway-session.json (mode 0600). Subsequent invocations without flags reuse the saved session.

Saved session?	Flags passed?	Behavior
No	All required flags	Connect, save session, start daemon
No	Any flag missing	Error — lists missing flags
Yes	None	Start daemon from saved session
Yes	Any flag	Reconnect with overrides, update session, start daemon

Running as a service

The daemon runs in the foreground until stopped with Ctrl+C. For supervised daemon mode, wrap the command in your init system. Replace /usr/local/bin/kylon with your actual install path (command -v kylon) — a global npm install may place the binary elsewhere, for example under a Node version manager.

[Unit]
Description=Kylon Gateway
After=network.target

[Service]
ExecStart=/usr/local/bin/kylon gateway run
Restart=always
User=your-user

[Install]
WantedBy=multi-user.target

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>io.kylon.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/kylon</string>
    <string>gateway</string>
    <string>run</string>
  </array>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

kylon gateway connect — Register a session without starting the daemon
kylon gateway start — Start the daemon from an existing saved session
kylon gateway bind — Bind an agent to a provider and working directory