> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your coding agent to Grid

> Run baseten grid setup to point Claude Code, Codex, OpenCode, or Pi at your team's Grid models.

Run `baseten grid setup` once to point your coding agent at your team's models on Baseten Grid. Setup finds the supported coding agents you have installed, adds your team's routes to each agent's model picker, and configures Grid credentials for your machine.

## Before you begin

* Your organization uses Grid, and an admin has added you to a team that has at least one route.
* You use a [supported coding agent](https://docs.baseten.co/grid/supported-agents-and-models.md) on macOS or Linux.

## What setup changes

Setup replaces each coding agent's model and endpoint settings with your team's routes and doesn't save the previous values. Setup keeps your MCP servers, plugins, and other settings.

If you've customized your agent's model or endpoint settings, copy its configuration file before you run setup. To see which files setup changes, run `baseten grid setup --dry-run --verbose`.

Claude Code, Codex, and Pi get short-lived Grid tokens from the Baseten CLI as they need them, so setup stores no long-lived key for them. For OpenCode, setup creates a Grid API key for your machine and team, named `baseten-harness-<hostname>-<suffix>`, and later runs reuse it. For Claude Code on a team with router routes, setup also offers to show which model served the latest response, in the status line or, if you already have one, after each response.

> [!WARNING]
>
> For Codex, setup also signs out of OpenAI and ChatGPT and disables ChatGPT login while Grid is configured. If Codex's background server is running, setup restarts it, and asks first when Codex sessions are attached to it.

## Connect your coding agents

**To connect your coding agents to Grid**:

1. Install or update the [Baseten CLI](https://docs.baseten.co/reference/cli/baseten/overview.md#install) to the latest version. With Homebrew, run the following commands:

   ```sh theme={"system"}
   brew tap basetenlabs/baseten
   brew trust --formula basetenlabs/baseten/baseten
   brew install baseten
   ```

   If you already have the CLI, run `brew upgrade baseten` instead.

2. Sign in to your organization:

   ```sh theme={"system"}
   baseten auth login
   ```

3. Run [`baseten grid setup`](https://docs.baseten.co/reference/cli/baseten/grid#setup) and pick the coding agents to configure:

   ```sh theme={"system"}
   baseten grid setup
   ```

   > [!NOTE]
   >
   > If you're on more than one team, pass `--team` with the team's name or ID. Setup saves the team, and `baseten grid sync` keeps using it. To skip the picker, pass `--harness` once for each coding agent:
   >
   > ```sh theme={"system"}
   > baseten grid setup --harness claude-code --team "<TEAM_NAME_OR_ID>"
   > ```

4. Review the planned changes and confirm.

5. Restart your coding agent so it reads the new settings.

6. In your coding agent's model picker, choose one of your team's routes, then [send a test request](#send-a-test-request) to verify the connection.

Setup uses your team's [harness defaults](https://docs.baseten.co/grid/set-up.md#set-harness-defaults) for each model role. To see them, run the following command:

```sh theme={"system"}
baseten grid team-settings describe
```

**To choose another team and primary model**:

Use the team's name or ID and an existing route's ID. Run `baseten grid route list` to find route IDs:

```sh theme={"system"}
baseten grid setup --harness claude-code --team "<TEAM_NAME_OR_ID>" --primary-route-id "<ROUTE_ID>"
```

Restart Claude Code and check that the selected route is its default model. For more information, see [Model roles](https://docs.baseten.co/grid/supported-agents-and-models.md#model-roles).

## Check your setup

Run `baseten grid status` to see each coding agent's installed version, configuration path, and configured routes:

```sh theme={"system"}
baseten grid status
```

Status reads local files only. It doesn't check your key or your team's current routes. Use it to inspect the configuration, then send a request to verify the connection.

### Send a test request

Restart your coding agent, choose a team route in its model picker, and send a short prompt:

```text theme={"system"}
Reply with exactly: Grid connection check.
```

A response confirms that the selected route can serve a request. To inspect that route's target, replace the placeholders and run the following command:

```sh theme={"system"}
baseten grid route describe --name "<ROUTE_NAME>"
```

For a model route, the target identifies the configured model.

To compare your spend this month with your limit, run the following command:

```sh theme={"system"}
baseten grid user-settings describe --team "<TEAM_NAME_OR_ID>"
```

Usage can take up to 15 minutes to appear. A response can succeed before the usage view updates.

### Check your tools

If you use MCP servers, ask your agent to perform a read-only task with one of your configured tools. Confirm that the agent makes the tool call and uses its result. Preserving the configuration doesn't verify that a server is authenticated or reachable.

Claude account connectors and MCP servers configured in Claude Code are different. Claude account connectors don't work while Claude Code points at Grid. Configure the tools as MCP servers in Claude Code instead; an external MCP manager can provide those servers.

## Pick up new routes

When your admin adds or changes routes, run [`baseten grid sync`](https://docs.baseten.co/reference/cli/baseten/grid#sync). Sync reapplies your last setup on every configured coding agent with the team's current routes and reuses your existing key:

```sh theme={"system"}
baseten grid sync
```

For Codex, sync can restart the background server and interrupt an in-progress turn. It asks before restarting when sessions are attached, unless you pass `--yes`.

Sync has no `--team` option. To change which coding agents or team you use, run `baseten grid setup` again.

## Remove Grid from a coding agent

[`baseten grid teardown`](https://docs.baseten.co/reference/cli/baseten/grid#teardown) removes the Baseten integration settings so the coding agent's own defaults apply. It keeps unrelated settings and doesn't restore previous values.

**To remove Grid from a coding agent**:

1. Preview what teardown removes:

   ```sh theme={"system"}
   baseten grid teardown --harness <AGENT> --dry-run
   ```

   Supported options for `<AGENT>` are `claude-code`, `codex`, `opencode`, and `pi`.

2. Run teardown:

   ```sh theme={"system"}
   baseten grid teardown --harness <AGENT>
   ```

3. If you copied a configuration file before setup, copy your previous model and endpoint settings back into it.

4. For Codex, sign back in to OpenAI:

   ```sh theme={"system"}
   codex login
   ```

5. Restart the coding agent, choose your previous model, and send a short request to verify the connection.

Teardown also deletes the Grid API key once no other coding agent on your machine uses it. Without `--harness`, it removes every integration configured at its default path.

## Troubleshooting

**Setup reports `there are <n> teams; pass --team`**: you're on more than one team. Run `baseten org team list` to see your teams, then pass `--team` with the team whose models you want.

**Setup reports `team <team> has no routes`**: your team doesn't have any routes yet. Ask your admin to add models to it.

**Setup reports that your team has no routes a coding agent can call**: Claude Code uses only routes that serve the Anthropic Messages API, and Codex uses only routes that serve the OpenAI Responses API. Ask your admin for a model that your coding agent can call.

**A route is missing from your coding agent**: first list the routes available in the intended team:

```sh theme={"system"}
baseten grid route list --team "<TEAM_NAME_OR_ID>"
```

If the route isn't listed, ask your admin to add it. If it is listed, run the following command, restart your coding agent, and check its model picker:

```sh theme={"system"}
baseten grid sync
```

If setup printed `warning: skipping routes without usable model metadata`, the route's model doesn't meet the [model requirements](https://docs.baseten.co/grid/supported-agents-and-models.md#model-requirements).

**Codex still shows its previous models after setup or sync**: setup and sync restart Codex's background server so it reads the new model catalog. If you declined the restart or it failed, sync retries it. The restart interrupts in-progress turns; Codex keeps the thread history.

**To retry a pending Codex restart**:

1. Finish active work in Codex.

2. Run sync:

   ```sh theme={"system"}
   baseten grid sync
   ```

3. Confirm the restart when prompted.

4. Reopen Codex and check that its model picker lists your team's routes.

**Your coding agent stops getting responses after working earlier**: you or your team may have reached a monthly spend limit. Run the following command for that team:

```sh theme={"system"}
baseten grid user-settings describe --team "<TEAM_NAME_OR_ID>"
```

For more information, see [Check your Grid usage](https://docs.baseten.co/grid/developers/usage.md).

**Setup reports `list routes: baseten API error (HTTP 403)`**: the CLI is signed in to an organization that doesn't use Grid, or you aren't on the team that owns the routes. If you belong to more than one Baseten organization, run `baseten auth login` again and sign in to the one that uses Grid. Otherwise, ask your admin to add you to the team.

**A Grid command reports `no team matched` or `HTTP 403` after you sign in**: if `BASETEN_API_KEY` is set in your shell, the CLI uses that key instead of your sign-in. To see which credential it uses, run the following command:

```sh theme={"system"}
baseten auth status
```

If the output includes `Using API key from BASETEN_API_KEY`, run `unset BASETEN_API_KEY` and try the command again. If you ran setup with that key, run `baseten grid setup` again so your coding agent uses your sign-in instead.

For more information, see the [`baseten grid`](https://docs.baseten.co/reference/cli/baseten/grid) CLI reference.