Skip to main content
Kai Code Bridge is a small background service that connects a computer or server of yours to Gleap. When it is running, Kai Code sessions can execute there instead of in the Gleap cloud, using your own AI subscriptions (Claude Code, Codex or Cursor). Your agent logins never leave that device.

​
Requirements

  • Git on the machine you want to connect.
  • Node 20 or newer and a terminal on that machine, or SSH access to it (a headless server works). Not needed if you set up with Gleap Desktop on macOS.
  • A Gleap user with access to the project.

​
Connect a machine

Run this in a terminal on the computer you want to connect:
The command installs the bridge, opens a pairing link in your browser, installs the background service and guides you through signing in to your coding agents. The machine shows up under Kai Code → Settings → Kai Code Bridge as soon as pairing completes, usually within a few seconds. Re-run the guided setup at any time. It shows the machine’s state (pairing, background service, agent sign-ins) and offers whatever is left to do:

​
With Gleap Desktop (macOS)

Gleap Desktop sets up the bridge for you, step by step. You don’t need Node.js or any commands.
  1. In Gleap Desktop, open Kai Code → Settings → Kai Code Bridge and click Connect Kai Code Bridge. You can also choose Add machine (or Set up) in the Run on picker.
  2. Click Start setup and go through the four steps. Each one starts with its own button:
    • Install: click Install. Kai Code Bridge is installed on your Mac in about a minute.
    • Connect: click Open approval window and approve your Mac in the window that opens.
    • Background: click Start in background, so Kai can reach your Mac even when Gleap Desktop is closed.
    • Sign in: pick Claude Code, Codex or Cursor and click Sign in. Log in in the window that opens.
  3. When your Mac shows as ready, pick it under Run on when you start a Kai Code session.
Steps that are already done are skipped, so a Mac that already runs the bridge from the terminal starts at the first open step. You can close the window at any time and pick up where you left off.
Kai needs Git. If it’s missing, macOS offers to install it. Click Install in the macOS window, then Try again.
Gleap Desktop installs its own copy of Node.js and the bridge into ~/.kai/runtime and sets up the same background service as the terminal setup. To use the kai-bridge commands on this page with the bridge Gleap Desktop installed, add it to your PATH in the terminal first:

​
Coding agents (harnesses)

Kai Code Bridge drives the coding agent that is installed on the machine. The guided setup installs and signs in Claude Code and Codex for you; Cursor is only available locally. To manage an agent by hand, run these on the machine running the bridge. Replace claude with codex or cursor. Install an agent if it is missing:
Sign in (your login stays on that device):
Update to the latest version:
On a server without a browser, Codex uses device-code sign-in automatically. You can force it with kai-bridge profile login codex --device-auth.
If a session stops because your coding agent is signed out on the Mac running Gleap Desktop, the message in Kai Code has a Sign in button that does this for you. The session continues once you’re signed in.

​
Choosing where a session runs

In the Kai Code composer, the Run on picker lists the Gleap cloud and every connected machine. Pick a machine to run the session there; previews and verification stay on that device, while photo and video proof is available in Kai Code as usual. A machine is shown as Away when it is asleep or the bridge service is not running. Start it again with:
Or run kai-bridge on its own: the setup screen shows why the machine is away and fixes it with one keypress. In Gleap Desktop, click Connect Kai Code Bridge again and then Start in background.

​
Check the bridge

See the machine’s tools, pairing, service, agent sign-ins and the repositories Kai can use:
See whether the background service is installed and running, and where its log is:
Watch what the bridge is doing while a session runs, for example when a machine looks stuck:
The bridge updates itself in the background. kai-bridge --version shows the installed version, and kai-bridge update installs the latest one right away.

​
Share a machine with your team

A connected machine is private by default: only you can pick it under Run on. To let everyone in your organisation run Kai Code sessions on it, open Kai Code → Settings → Kai Code Bridge, open the machine and switch Visibility to Public, or choose Make public from the row’s menu. Teammates then see it under Run on as shared by you, and under Shared with you in their own Kai Code Bridge settings.
Sessions teammates start on a public machine run with that machine’s coding-agent sign-ins and push commits with its git identity, so your own subscription limits apply. Teammates cannot sign in, install coding agents or add folders on your machine. Those actions stay with you.
Switch back to Private at any time. Sessions a teammate already started on the machine stop with a note the next time they send a message, and they can continue in the Gleap cloud or on their own machine.

​
Saved app sign-ins

When Kai verifies a change in your app and hits a login wall, it asks you once for a sign-in. Sign-ins are encrypted per repository and device, stored on the bridge machine only, and removed after 30 days without use. You can forget one at any time under Kai Code → Settings → Kai Code Bridge → Saved app sign-ins.

​
Disconnect a machine

Open Kai Code → Settings → Kai Code Bridge, open the machine and choose Disconnect. Then stop the service on the machine:
Or do both from the machine itself: kai-bridge logout disconnects it from Gleap and removes the service. Your coding-agent logins stay on the machine either way.