> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcaplabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Security & approvals
> Headmaster's layered security model — approval gates, container isolation, secret exfiltration blocking, file access controls, and a killswitch.
# Security & approvals
Headmaster is designed to keep you in control of what the agent does. The security model has several layers — from approval gates to container isolation to secret blocking.
***
## Approval gates
The core security mechanism. In **Work Along** mode, the agent asks for your approval before every action that affects your system:
* ⌨️ Running a terminal command
* 📁 Reading or writing a file outside the project folder
* 🌐 Making a network request (external API call, HTTP request)
* ⚙️ Executing code
* 🔌 Calling an MCP tool
* 💬 Sending a message on a channel
In **Run It Yourself** mode, the agent runs most things without asking, but still requires approval for destructive actions: deleting a file, overwriting a file, sending messages, force-pushing to git, or running sudo commands.
In **Hands-Off** and **Autopilot**, no approval prompts. All actions are logged.
See [Approvals & human-in-the-loop](/approvals-human-in-the-loop) for the full approval flow.
***
## Container isolation
If you use a container terminal backend (Docker, Singularity, Modal, Daytona), the agent's terminal commands run inside an isolated container — not on your host machine.
| Protection | How it works |
| ----------------------------- | ------------------------------------------------------- |
| **Read-only root filesystem** | The agent can't modify system files. |
| **Capabilities dropped** | No root access, no kernel access. |
| **No privilege escalation** | The agent can't escalate to root. |
| **PID limits** | Max 256 processes — prevents fork bombs. |
| **Namespace isolation** | Separate network, filesystem, and process namespace. |
| **Workspace volume** | Agent writes to `/workspace`, not your host filesystem. |
See [Terminal backends](/terminal-backends) for configuration.
***
## Secret exfiltration blocking
Headmaster blocks the agent from exfiltrating secrets — your API keys, passwords, and tokens:
* 🔗 **URL encoding** — can't encode secrets in URL parameters to send externally.
* 🔒 **Base64 encoding** — can't base64-encode secrets to obfuscate them before sending.
* 🧠 **Prompt injection** — the agent is trained to recognize and resist attempts by web pages or file content to reveal secrets or run unauthorized commands.
* 🌿 **Env var access** — the agent reads only explicitly configured env vars, not a full env dump.
When the agent detects an attempted exfiltration, it refuses the action, logs the attempt, and reports it in the chat.
***
## High-risk command approval
Even in Hands-Off mode, these commands are flagged and require explicit approval:
```
rm -rf recursive force delete
sudo privilege escalation
chmod 777 world-writable permissions
git push --force force push to remote
curl | bash pipe a remote script to bash
dd low-level disk operations
mkfs filesystem formatting
```
The list is configurable in **Settings → Headmaster's Library → Advanced → Dangerous commands**.
***
## File access control
| Mode | Project folder | Outside project folder |
| ------------------- | ------------------------------- | --------------------------------------------- |
| **Work Along** | Read/write — no approval needed | Approval needed for every access |
| **Run It Yourself** | Read/write — no approval needed | Approval needed for writes; reads are allowed |
| **Hands-Off** | Read/write — no approval needed | Blocked — can't access files outside project |
This prevents the agent from accidentally reading your SSH keys, browser cookies, or other sensitive files.
***
## Network access
| Mode | External requests |
| ------------------- | ------------------------------------------ |
| **Work Along** | Approval needed for every external request |
| **Run It Yourself** | Allowed, no approval, but logged |
| **Hands-Off** | Allowed, no approval, but logged |
| **Autopilot** | Allowed, no approval, but logged |
All network requests are logged with URL, method, timestamp, and response status.
***
## Credential storage
| Credential type | How it's stored |
| ----------------------- | ------------------------------------------ |
| API keys | Encrypted at rest with envelope encryption |
| Channel tokens | Encrypted at rest |
| Integration credentials | Encrypted at rest |
| MCP server env vars | Encrypted at rest |
For encryption at rest of the full data folder, use FileVault (macOS), BitLocker (Windows), or LUKS (Linux).
***
## Rate limiting
* **WebUI login** — 3 wrong attempts = 60-second lockout, 5 wrong attempts = 5-minute lockout.
* **PIN gate** — same rate limiting for Headmaster's Library.
* **Provider API keys** — multi-key rotation with 90-second blacklisting for failed keys.
***
## Killswitch
Interrupts the current action immediately. Also kills all running subagents.
Tears down the entire runtime process and starts fresh. Kills all tasks, scheduled triggers, and subagents.
***
Full details on the approval flow — prompts, clarifications, permission requests.
Configure container isolation for the agent's terminal.