Agent permissions

You can let an agent create devboxes, organize work, or update project settings through Agent permissions. To control whether the agent asks before editing files or running commands, choose Claude's working mode or set a custom command policy for Codex or Claude.

Allow boxes.dev operations

Open one of your threads and select Agent permissions in its header. The control shows the permissions of the exact Template box or devbox the thread runs on. The switches show whether each permission is on or off, including permissions enabled through Project settings. A permission you turn on will apply to every agent on that machine until you turn it off.

If an agent needs a disabled permission for your task, it can show a request with Deny, Allow, and, where supported, Always allow for project. Suppose you asked Codex to move its devbox into your Planning folder while folder access is off: choosing Allow will turn folder access on for that machine, just as if you had enabled it yourself; it is not a one-time exception for that move. Choose Deny to decline this request without changing any permission settings.

The controls include:

• Create devboxes and threads: allow agents to start additional work in this project.
• Update thread titles: allow agents to rename their current thread.
• Folder access: choose no access, permission to move devboxes into folders, or permission to move devboxes and create folders.
• Message other agents: allow agents on the machine to send messages to your other agents in this project and receive their messages. A message will start an idle agent and wake its devbox if it's asleep. Both machines need this permission.
• Read other threads: choose this project, all your projects, your threads plus threads shared with you, or your threads plus teammates' threads you can access. Each level includes the preceding levels. Team visibility and private-thread settings still apply. Agents will only be able to read these other threads, not send messages or control them.

On an ordinary devbox, Destroy and archive this devbox lets agents request its deletion after all agents finish. This permission is off by default and applies only to that devbox. Files are permanently deleted; thread history is retained. Turning the permission off cancels a pending request. An agent can also cancel with dvb-onbox box cancel-destroy, even when this permission is off; cancellation is available only before destruction starts.

On an ordinary Template box, you can also enable Edit devbox lifecycle for startup and teardown settings, or Edit template maintenance for the maintenance script and its GitHub watches. Team admins can enable Create Team Templates to let agents create, configure, and save Team Templates.

Let one thread edit your Template

If you ask an agent on a devbox to change the Template that devbox came from, it can ask for access in that thread. The request shows Allow for 3 hours and Deny. Access will apply only to that thread and will end 3 hours after you allow it. Other threads and devboxes won't receive it, and it isn't one of the Agent permissions switches.

In a project with its own Template box, the agent will be able to run commands on your Template box, change the project's environment variables, and take a snapshot that future devboxes will use. In a Team Template project, you need to be a team admin; the agent will be able to open the Team Template's editing session, change it and its environment variables, and save a new version for your team. If you save that editing session yourself in the desktop app, the agent's access to it will end.

In a Team Template project, any member can also let a thread edit their own environment variables. That request asks Allow this thread to edit your environment variables?, and the agent will be able to add, change, and remove your own variables and your values for the team's Member variables, which reach all your devboxes in the project. It can't change Team values or read saved values.

Share permissions across your project

Open Settings → Project settings → Agent permissions for this project to choose shared settings for creating devboxes and threads, updating thread titles, folder access, reading other threads, and messaging other agents. Changes will apply to your existing and future devboxes, except those you've configured separately. These are your permissions, including in a Member project; they will not change a teammate's permissions.

In an agent's permission request, choose Always allow for project to grant shared access. This will also enable the permission on the requesting box. Other boxes will keep any permissions you've set individually.

To give a particular box different permissions, change them in its thread header. That choice will apply to the box even when the project setting changes. Turning off shared access will revoke it on boxes that follow the project setting; permissions set individually will remain. Some older boxes also have permissions saved individually. To turn those off, use the box's Agent permissions control. Template-only permissions keep their existing scope.

Project settings control shared agent permissions for existing and future devboxes. Select the image to enlarge it.

Choose Claude's working mode

Claude's working mode controls approvals for edits and commands in that thread. It does not change the boxes.dev operations allowed through Agent permissions. In a connected Claude thread, use the mode control near the reply box to choose how Claude should work. The available choices depend on the machine and model:

Your confirmed Full-access, Auto, or Manual choice stays with the thread unless a custom machine policy overrides it when the agent restarts. Plan is temporary: when Claude shows Exit plan mode, choose Allow to return to the previous mode and let it implement the plan, or Deny to keep planning. If Auto becomes unavailable, Claude can return the thread to Manual.

Advanced: custom command policies

Codex normally makes ordinary edits and runs commands on its machine without individual approvals; to change that, set a custom command policy on the machine. For either agent, a policy can require approval for commands outside an allowlist, and command hooks can run your own checks around agent tools.

To set them up, read the machine README under /etc/boxes/agents/codex/ or /etc/boxes/agents/claude/. Finish active work and reboot to activate policy changes; reboot preserves files but stops workloads. See Custom command policies for file formats, activation, and recovery details.