Approvals and Permissions
Approvals and permissions control how AgentOS tools are allowed to act. They matter most when an agent can write files, run shell commands, publish artifacts, post into channels, or call external services.
Use this page before running unattended automation or giving a channel-connected agent broad tool access.
Permission Profiles
Single-shot automation accepts an explicit permission profile:
agentos agent --permissions restricted -m "Inspect this repo"
agentos agent --permissions on -m "Run with host execution and approvals"
agentos agent --permissions bypass -m "Trusted local automation"
agentos agent --permissions full -m "Fully trusted local automation"
Practical meaning:
| Profile | Use when |
|---|---|
restricted / off | The task should stay conservative and avoid elevated execution. |
on | Host execution is allowed, but approval checks still matter. |
bypass | You trust the task enough to auto-grant approvals while keeping sensitive-path checks. |
full | You fully trust the task and environment. Use sparingly. |
For automation, prefer the narrowest profile that can complete the task.
Workspace Containment
Set a workspace for file and shell work:
agentos agent \
--workspace /path/to/project \
--workspace-strict \
-m "Summarize this repo"
Contain writes to the workspace or scratch directory:
agentos agent \
--workspace /path/to/project \
--workspace-lockdown \
--scratch-dir /path/to/project/.scratch \
-m "Investigate and prepare a minimal patch"
Use --workspace-lockdown for unattended runs where accidental writes outside
the project would be unacceptable.
Interactive Approvals
Interactive chat surfaces can pause sensitive tool calls for a human decision. The terminal chat supports:
/approvals
/approvals reset
/permissions status
/permissions on
/permissions off
/permissions bypass
/permissions full
/forget
Use these commands when you need to inspect or reset cached approval decisions during a chat.
The Web UI also provides an approvals surface for reviewing pending actions outside the message scrollback.
Sandbox Posture
Inspect sandbox posture:
agentos sandbox status
agentos sandbox status --json
Set posture:
agentos sandbox on
agentos sandbox bypass
agentos sandbox full
agentos sandbox reset
Restart the gateway after changing global sandbox posture:
agentos gateway restart
Recommended Defaults
| Situation | Recommended approach |
|---|---|
| First run in a repo | --workspace plus --workspace-strict |
| Read-only investigation | --permissions restricted |
| Local patch with tests | --workspace-lockdown plus a scratch directory |
| Web UI task with writes | Keep approvals visible and review sensitive actions |
| Channel-connected agent | Conservative permissions and explicit channel setup |
| Unattended automation | Bound timeout/iterations and choose the narrowest workable permissions |
Troubleshooting
If a tool is denied:
agentos sandbox status
agentos doctor
Then check:
- whether the surface supports live approvals;
- whether the workspace path is correct;
- whether cached approvals need to be reset;
- whether the task should run with a different permission profile.
Read next: