> ## 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 creates a Grid API key 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 overwrites each coding agent's model and Baseten endpoint settings without saving their previous values, and replaces the agent's model picker with your team's routes. MCP servers, plugins, and other unrelated settings stay as they are. Setup creates a Grid API key on the first run, named `baseten-harness-<hostname>-<suffix>` by default, and reuses it afterward.

> [!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 the [Baseten CLI](https://docs.baseten.co/reference/cli/baseten/overview.md#install). With Homebrew, run the following commands:

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

2. Sign in and select 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
   ```

   If you're on more than one team, replace `<team>` with the team's name or ID and pass it with `--team`. To configure one coding agent without the picker, pass `--harness`, and repeat it to select several:

   ```sh theme={"system"}
   baseten grid setup --harness claude-code --team "<team>"
   ```

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. Run the following command to see them for your team:

```sh theme={"system"}
baseten grid harness-defaults --team "<TEAM_NAME_OR_ID>"
```

**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 background, subagent, and fallback models, see [Model roles](https://docs.baseten.co/grid/supported-agents-and-models.md#model-roles).

To preview the changes without writing files or creating a key, add `--dry-run`:

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

## 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`.

To change which coding agents or team you use, run `baseten grid setup` again instead.

## 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 codex --dry-run
   ```

2. Run teardown:

   ```sh theme={"system"}
   baseten grid teardown --harness codex
   ```

3. For Codex, run `codex login` to sign back in to OpenAI.

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. 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).

**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.

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