Skip to main content
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

FlagRequiredDescription
--server-urlOn first runKylon API URL (e.g. https://api.kylon.io)
--providerOn first runAgent provider: codex, claude-code, or generic
--api-keyOn first runAgent API key (starts with pak_)
--provider-argNoExtra argument passed to the provider process. Repeat once per argument token.
--provider-optionNoAlias 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
NoAll required flagsConnect, save session, start daemon
NoAny flag missingError — lists missing flags
YesNoneStart daemon from saved session
YesAny flagReconnect 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: 
[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
  • 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