Tune Agent Permissions And Folder Access

After the first successful run, tune what the agent can see, which tools it can use, and when Apprentice should ask before an action runs.

Apprentice agents run in isolated Docker containers. They do not need access to your whole computer. Give each agent the smallest folder and tool scope that matches its job, then expand that scope after reviewing real runs.

Where To Configure This

Open the agent, then use these tabs:

• Directories: choose the primary directory and mounted host folders.
• Permissions: choose approval mode, saved permission patterns, website rules, and command rules.
• Capabilities: enable or disable broad tool families such as filesystem, shell process, web network, browser, memory, tasks, messaging, scheduler, notifications, and external MCP tools.
• AI Guardrails: add optional AI review before sensitive actions.

These controls work together. For example, a permission mode may allow an action, but a disabled capability, blocked command, blocked website, or guardrail can still stop it.

Start With A Narrow Scope

For a new agent, start with:

• Permission Mode: Ask for Approval.
• Folder access: only the project or folder the agent needs.
• Volume mode: RO unless the agent must write files.
• Capabilities: disable tool families the agent does not need.
• Guardrails: optional, useful for sensitive agents or higher-risk actions.

This gives you a clean first run and makes unexpected behavior easier to spot.

Configure Folder Access

Use the Directories tab to set the agent's workspace.

The primary directory is the default working directory for the agent.

Volumes are host folders mounted into the agent container under the agent's home directory. For example, a volume named project appears inside the container as:

~/project

Use clear mount names, such as:

project
docs
exports

Avoid mounting your whole home folder, whole drive, secrets folders, or cloud-sync folders unless the agent truly needs that access.

Choose RO Or RW

Each mounted volume can be read-only or read-write.

Use RO when the agent should inspect, summarize, search, or answer questions from files.

Use RW only when the agent should create, edit, delete, or generate files in that folder.

If an agent cannot write to a folder, check whether the mounted volume is set to RO. If an agent can write more than intended, switch the volume back to RO or remove it.

Choose A Permission Mode

Apprentice supports these permission modes:

• Ask for Approval: the agent asks before tool operations. This is the safest default.
• Auto-Accept Safe Operations: low-risk operations can proceed automatically, while higher-risk actions still use policy and prompts.
• Deny All: blocks tool use for chat-only agents.
• YOLO / Allow All Operations: approves operations automatically. Use only for trusted agents in disposable or tightly scoped workspaces.

Avoid YOLO while you are still learning what an agent will do.

Use Website And Command Rules

When using Auto-Accept Safe Operations, you can tune allowed and blocked websites and commands.

Blocked rules take priority over allowed rules.

Useful examples:

github.com
api.example.com
git *
npm run *

Blocked examples:

sudo *
rm -rf *
*.unknown-domain.example

Keep rules specific. Broad rules are convenient, but they are harder to reason about later.

Use Permission Prompts Carefully

When an agent asks to use a tool, Apprentice shows the tool name and input.

You can:

• Deny: block the request.
• Allow: approve this request once.
• Always Allow: save a grant pattern for future matching requests.

Use Always Allow only when the pattern is narrow and understandable. A pattern like git * is easier to reason about than *.

Tune One Thing At A Time

After each run:

1. Open Activity.
2. Review the run detail and tools used.
3. Decide whether the agent needed more access or tried to do too much.
4. Change one setting.
5. Run the same test again.

This makes permission changes traceable instead of turning the agent into a broad-access automation box.

Common Setups

Read-only project analyst:

• Mount the project folder as RO.
• Use Ask for Approval.
• Keep shell process disabled unless needed.

Documentation editor:

• Mount the docs folder as RW.
• Keep source code folders RO or unmounted.
• Allow only the commands needed for documentation checks.

Automation helper:

• Mount one output folder as RW.
• Use explicit command rules.
• Set budget and guardrails before connecting schedules or integrations.

Troubleshooting

If the agent cannot see files, check the Directories tab and confirm the folder is mounted.

If the agent sees the wrong path, check the mount name. A volume named project is available as ~/project.

If writes fail, check whether the volume is RO.

If the agent asks for too many permissions, narrow its instructions, add specific saved patterns, or adjust command and website rules.

If an action is blocked unexpectedly, check Capabilities, blocked rules, guardrails, and permission patterns.

Next Step

After folder access and permissions are tuned, configure budgets and runtime limits.