Skip to main content

​
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 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. See 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:
The list is configurable in Settings → Headmaster’s Library → Advanced → Dangerous commands.

​
File access control

This prevents the agent from accidentally reading your SSH keys, browser cookies, or other sensitive files.

​
Network access

All network requests are logged with URL, method, timestamp, and response status.

​
Credential storage

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

Stop button

Interrupts the current action immediately. Also kills all running subagents.

Restart runtime

Tears down the entire runtime process and starts fresh. Kills all tasks, scheduled triggers, and subagents.

Approvals

Full details on the approval flow — prompts, clarifications, permission requests.

Terminal backends

Configure container isolation for the agent’s terminal.