Agent settings

Agent settings keep Claude and Codex settings the same on every box in a project. For example, you can change when agents compact long conversations or allow a command without asking, and the Template box and every devbox in the project will use the new setting. You don't need to take a snapshot.

Change settings for a project

1. In the desktop app, select your project, expand Settings near the bottom of the thread list, and open Project settings.
2. Expand Agent settings and choose the Claude or Codex tab.
3. Enter the settings you want. The Claude tab uses JSON in the format of Claude's settings.json, and the Codex tab uses TOML in the format of Codex's config.toml.
4. Choose Save. boxes.dev will indent Claude settings consistently when it saves them; Codex settings will be saved exactly as you wrote them.

For example, this Claude setting sets the context window size Claude uses to decide when to compact a long conversation:

{
  "autoCompactWindow": 400000
}

This Codex setting makes Codex compact a conversation when it reaches 300,000 tokens:

model_auto_compact_token_limit = 300000

Running boxes will update within a minute, sleeping boxes will update when they wake, and new devboxes will start with the saved settings. Claude reads some settings, such as autoCompactWindow, only when a session starts, so start a new session to use them. Codex applies changes to new threads.

If someone else saved the same tab after you opened it, the card will say These settings were changed elsewhere. Choose Load latest, then make your change again.

How boxes.dev updates each box

boxes.dev writes your saved settings into ~/.claude/settings.json or ~/.codex/config.toml on each box and changes only those settings. Other settings in these files stay as they are, including ones you or an agent added on a box. Nested settings are combined one key at a time, so saving one env variable keeps the box's other env variables. A Claude list such as permissions.allow will add your items to the box's list, but a Codex list will replace the box's list.

If you remove a setting from the card, boxes.dev will remove it from every box. The box won't get back the value it had before you saved the setting. If someone changes a saved setting directly on a box, boxes.dev will change it back within a minute.

Your repository's own .claude/settings.json or .codex/config.toml takes precedence over these settings.

Check values before saving

Before saving, boxes.dev checks that the text is valid JSON or TOML. It also checks each setting against the version of Claude Code or Codex that boxes.dev installs:

• A wrong value that would stop Codex from starting or make Claude Code ignore the whole settings file can't be saved. The card will name the setting and what the agent needs, for example "Codex (v0.159.0) needs model_auto_compact_token_limit to be a whole number."
• Claude Code skips a wrong value in some settings, such as effortLevel, and still reads the rest of the file. For those, the card will show a warning, and you can still save.
• If the agent doesn't recognize a setting, the card will show a warning, and you can still save. Check the spelling. A setting from a newer version of the agent will be ignored until boxes.dev installs that version.

Plugins and MCP servers have their own pages, so the card won't save settings such as enabledPlugins, plugins, or mcp_servers. Use Install agent plugins and Add MCP servers instead.

Settings from a Team Template

Team admins can choose agent settings for projects created from a Team Template: open Agent settings on the template detail page, edit the Claude or Codex tab, and choose Save. How the settings reach a project depends on its type:

• In a Member project, every devbox will use the team settings together with the member's own. In their project's Agent settings card, members can expand the team settings to read them and save their own settings below. Where both set the same option, the member's value will be used. Claude lists will include the items from both, and a member's Codex list will replace the team's. A saved team change will reach existing devboxes within a minute.
• An independent project will receive a copy of the template's settings when it is created. Later team changes won't reach existing projects, and each owner can edit their copy in Project settings.

Ask an agent to change settings

An agent on a box can read and save agent settings with dvb-onbox project settings, and an agent working for a team admin can save team settings with dvb-onbox team-template settings. Saving needs an editing permission that you approve; see Read and edit project and Team Template settings.