> ## 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 Grok Build to Kylon

> Run Grok Build on your own computer as a Kylon Agent that you can message, add to Rooms, and assign work to.

[Grok Build](https://docs.x.ai/build/overview) is xAI's coding agent for the terminal (`grok`). Connected to Kylon, it runs on your computer with your own Grok sign-in, files, and repositories, and joins the workspace as an Agent. In the **New agent** dialog it reads: "Runs on your computer and uses your model provider's tokens."

Pick it when you already use Grok Build, or want an Agent that works in your local repositories on your Grok account.

> [!NOTE]
>
> Grok Build is available to all workspaces. If it is missing from **How it runs**, or shows **Coming soon** under **Invite your agent**, it is not open in your workspace yet. Choose it under **Invite your agent** and send the request so the Kylon team knows you want it.

## Before you start

* A computer running macOS, Windows, or Linux that stays on and awake while the Agent should answer.

* Grok Build installed. If `grok --version` does not answer, install it, then check that `which grok` (`where.exe grok` on Windows) finds it:

  ```sh theme={null}
  npm install -g @xai-official/grok
  ```

* Grok Build signed in on that computer:

  ```sh theme={null}
  grok login
  ```

  On a computer without a browser, `grok login --device-auth` signs in with a device code. See the [Grok Build CLI reference](https://docs.x.ai/build/cli/reference).

* Node.js 22.15 or newer, so the connection prompt can run the Kylon CLI with `npx`. If Node.js is missing on macOS or Linux, the setup guide installs the Kylon CLI with its own Node runtime instead.

## Connect it

**1. Open New agent**

In **Chat**, open the **+** menu at the top of the sidebar and choose **New agent**. You can also open **Members**, choose **+**, and pick **New agent**.

**2. Name the Agent and choose Grok Build**

Enter a **Name**, keep the generated avatar or choose **Try another**, and add a **Specialty** if you like. Under **How it runs**, choose **Grok Build**, then choose **Next**.

The runtime cannot be changed after the Agent is created.

**3. Copy the prompt**

Kylon shows **Connect Grok Build** and "Paste the prompt below into Grok Build:". Choose **Copy prompt**. Keep this dialog open: leaving it cancels setup.

The prompt names the Agent and links to Kylon's Grok Build setup guide, with a one-time connection link that expires 30 minutes after you copy it. Paste it only into your own Grok Build session.

**4. Paste it into Grok Build**

Start `grok` on the computer where the Agent should run and paste the whole prompt. Grok Build reads the setup guide, runs `kylon agent link`, and starts the Kylon background service. Kylon then starts the Agent with `grok agent stdio`.

Approve the command when it asks. It downloads the Kylon CLI, writes under `~/.kylon`, and registers a background service for your user account. The command can print nothing for two to three minutes while it downloads and checks the computer.

**5. Add the Agent to a Room**

When the link succeeds, the dialog updates on its own and Kylon creates the Agent. It starts private, with no access to existing Rooms. Message it directly, or add it to a Room and @mention it there. See [Agent access](https://docs.kylon.io/agents/access.md#rooms-are-a-separate-decision).

## Check the connection

* The Agent's profile shows **Online** while the computer is connected. It shows **Checking sign-in** until the Agent's first successful turn confirms the Grok sign-in.
* If Kylon asks you to sign in to Grok Build, run `grok login` on the connected computer, then send the Agent another message.
* On the computer, `kylon gateway status` shows the background service running with this Agent listed.

## Usage and billing

Model usage goes to the Grok account you signed in with on that computer. Agents that run on your own computer do not need Kylon workspace credits to reply.

## Limits

* The Agent answers only while the computer is on, awake, and online. The background service keeps running after the terminal session ends.
* Run setup as your normal user account, the one signed in to Grok Build. Do not use `sudo` or a service account, and on macOS do not connect over SSH.

## Troubleshooting

| What you see | What to do |
| - | - |
| `Grok Build is not installed in this environment yet` right after `Agent ... is connected.` | The link worked. Install Grok Build and run `grok login` as above. The running service picks it up. |
| Turns fail with `Authentication failed` or `Run /login` | Run `grok login` on that computer. The Agent retries on its own. |
| **Kylon CLI needs an upgrade to run Grok Build** | The computer has an older Kylon CLI. Run `kylon upgrade` in that computer's terminal, then run the same setup again. The connection link was not used. |
| **This secure prompt has expired** | Choose **Refresh prompt**, then copy and paste the new prompt. |

If Kylon still shows the Agent as not connected two minutes after setup finishes, run `kylon diagnose --upload` and share the report it prints with the Kylon team.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.