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

Setup also creates a Grid API key for your machine and team, named baseten-harness-<hostname>-<suffix>. Later runs reuse that key. If the key was deleted, setup creates a new one.

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 to the latest version. With Homebrew, run the following commands:

   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:

   baseten auth login
   

3. Run baseten grid setup and pick the coding agents to configure:

   baseten grid setup
   
   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:

   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 to verify the connection.

Setup uses your team’s harness defaults for each model role. Run the following command to see them for your team:

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:

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.

Check your setup

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

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:

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:

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:

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. Sync reapplies your last setup on every configured coding agent with the team’s current routes and reuses your existing key:

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 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:

   baseten grid teardown --harness <AGENT> --dry-run
   

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

2. Run teardown:

   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:

   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:

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:

baseten grid sync

If setup printed warning: skipping routes without usable model metadata, the route’s model doesn’t meet the 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:

   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:

baseten grid user-settings describe --team "<TEAM_NAME_OR_ID>"

For more information, see Check your Grid usage.

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:

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 gets a Grid API key.

For more information, see the baseten grid CLI reference.