Skip to main content
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 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.
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. With Homebrew, run the following commands:
  2. Sign in and select your organization:
  3. Run baseten grid setup and pick the coding agents to configure:
    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:
  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:
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:
Restart Claude Code and check that the selected route is its default model. For background, subagent, and fallback models, see Model roles. To preview the changes without writing files or creating a key, add --dry-run:

​
Check your setup

Run baseten grid status to see each coding agent’s installed version, configuration path, and configured routes:
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:
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:
For a model route, the target identifies the configured model. To compare your spend this month with your limit, run the following command:
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:
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 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:
  2. Run teardown:
  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:
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:
If setup printed warning: skipping routes without usable model metadata, the route’s model doesn’t meet the 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:
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. For more information, see the baseten grid CLI reference.