AgentOS markAgentOS
Install AgentOS

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