Sandboxing and Security
Relevant source files
The following files were used as context for generating this wiki page:Sandboxing and security are critical components of the pi-mono project, designed to isolate and control code execution from AI agents. The project employs a multi-layered approach, with distinct sandboxing mechanisms for the backend agent (mom) and the frontend components (web-ui, coding-agent). The primary goal is to provide powerful tools to the agents while mitigating risks like prompt injection, credential exfiltration, and system damage.
The backend mom agent utilizes Docker containers for robust isolation of shell commands, while the frontend web-ui and coding-agent use sandboxed iframes to safely execute JavaScript and render HTML artifacts in the browser. These technical measures are complemented by detailed security instructions embedded within the agents' system prompts, guiding them on safe tool usage and interaction patterns.
mom Agent Sandboxing
The mom agent is designed to execute shell commands, read/write files, and manage its own environment. To secure these powerful capabilities, it uses a sandbox executor that can operate in two modes: Docker (recommended) or Host (not recommended).
Sources: packages/mom/src/sandbox.ts, packages/mom/README.md
Execution Environments
The execution environment is determined by the --sandbox CLI option when starting the mom agent.
| Mode | CLI Flag | Description | Security Posture |
|---|---|---|---|
| Docker | --sandbox=docker:<name> | Commands execute inside an isolated Linux (Alpine) container. The agent can only access a mounted data directory. | Recommended. Protects the host system. Credentials are still at risk if stored within the container. |
| Host | --sandbox=host | Commands execute directly on the host machine with the user's permissions. | Not Recommended. The agent has full access to the host system, including SSH keys and all files. |
Sources: packages/mom/README.md, packages/mom/src/sandbox.ts:11-12
The following diagram illustrates the command execution flow for the mom agent.
This diagram shows how the Sandbox Executor routes a bash command to either a Docker container or the host system based on the CLI configuration.
Sources: packages/mom/src/sandbox.ts:25-55, packages/mom/src/sandbox.ts:63-87
Security Considerations for mom
The mom/README.md explicitly details significant security risks and mitigations.
Prompt Injection
Both direct and indirect prompt injection attacks are identified as major threats.
- Direct Injection: A malicious user directly asks the agent to reveal sensitive information (e.g.,
cat ~/.ssh/id_rsa). - Indirect Injection: The agent processes malicious content (e.g., from a cloned git repository) that contains hidden instructions to exfiltrate data.
Sources: packages/mom/README.md
Mitigations
The documentation recommends several strategies to minimize risk:
- Use Docker Mode: Always run in a Docker sandbox to isolate the agent from the host system.
- Principle of Least Privilege: Use dedicated bot accounts and API tokens with minimal, read-only permissions where possible.
- Isolate Instances: Run separate
mominstances with different data directories and credentials for different teams or security contexts. - Monitoring: Regularly check tool call logs, which are stored in threads for transparency.
- Auditing: Periodically review the contents of the data directory to know what credentials the agent has access to.
Sources: packages/mom/README.md
web-ui Frontend Sandboxing
The web-ui package uses a SandboxedIframe Lit web component to execute untrusted JavaScript code (from the REPL tool) and render HTML artifacts in a secure manner. This prevents the code from accessing the main application's DOM, cookies, or localStorage.
Sources: packages/web-ui/src/components/SandboxedIframe.ts, packages/web-ui/src/tools/javascript-repl.ts, packages/web-ui/src/tools/artifacts/HtmlArtifact.ts
Architecture
The sandboxing system is composed of several key classes that work together to create an isolated environment and manage communication.
This diagram shows the relationship between SandboxIframe and its collaborators. HtmlArtifact and the javascript-repl tool use SandboxIframe to run code, which in turn uses SandboxRuntimeProviders to inject functionality and communicates via the RuntimeMessageRouter.
Sources: packages/web-ui/src/components/SandboxedIframe.ts, packages/web-ui/src/tools/artifacts/HtmlArtifact.ts, packages/web-ui/src/tools/javascript-repl.ts
Key Security Features
The SandboxedIframe implements several security measures:
| Feature | Description | Implementation |
|---|---|---|
Iframe sandbox Attribute | Restricts iframe capabilities. allow-scripts is enabled to run code, and allow-modals is enabled for user interactions like alert(). Other permissions like allow-same-origin are disabled. | The sandbox attribute is set on the HTMLIFrameElement. |
| Navigation Interception | Prevents the sandboxed content from navigating the top-level page. All link clicks and form submissions are intercepted and opened in a new tab via window.parent.postMessage. | A "Navigation interceptor" script is injected into the sandbox, adding event listeners for click and submit, and overriding window.location. |
| Script Content Escaping | Prevents premature script tag closure when injecting user code. The sequence </script is escaped to <\\/script. | The escapeScriptContent function is used before injecting code into <script> tags. |
| HTML Validation | Before loading content into the iframe, the HTML is validated using DOMParser. If an error is found, it is displayed in the iframe instead of loading the potentially broken content. | The validateHtml method uses parser.parseFromString and checks for a <parsererror> element. |
| Execution Timeout | A 120-second timeout is enforced for code execution in execute() mode (used by the JavaScript REPL) to prevent infinite loops. | A setTimeout is created in the execute method, which rejects the promise if not completed in time. |
Sources: packages/web-ui/src/components/SandboxedIframe.ts:159, 241, 38-41, 416-421, 518-538, 321-332
Code Execution Flow (execute)
The execute method is used by the JavaScript REPL to run code and get a result. It's an asynchronous process involving message passing between the main window and the sandboxed iframe.
This sequence shows the execute method flow. The SandboxIframe creates an iframe, which runs the code. The sandboxed environment uses postMessage to send events like console logs or completion signals back to the main application via the RuntimeMessageRouter.
Sources: packages/web-ui/src/components/SandboxedIframe.ts:260-409, packages/web-ui/src/tools/javascript-repl.ts:18-77
Content Loading Flow (loadContent)
The loadContent method is used by HtmlArtifact to render and display persistent HTML content. Unlike execute, it does not have a timeout and the iframe remains visible.
This flow shows how HtmlArtifact uses loadContent to safely render HTML, including a validation step.
Sources: packages/web-ui/src/components/SandboxedIframe.ts:90-147, packages/web-ui/src/tools/artifacts/HtmlArtifact.ts:110-142
Prompt-Level Security
In addition to technical sandboxing, the system relies heavily on instructions within the agent's system prompt to enforce security policies and guide behavior.
mom Agent Prompt
The system prompt for the mom agent provides explicit instructions on its environment and how to interact with it safely.
- Environment Description: Clearly states whether it's in Docker or on the host and what that implies (e.g.,
apk addfor Docker). - Workspace Layout: Defines the strict directory structure (
/workspace/<channelId>/...) the agent must adhere to. - Log Queries: Provides specific
jqcommands to querylog.jsonlsafely, with an emphasis on limiting output to avoid context overflow. - System Log: Instructs the agent to maintain a
SYSTEM.mdfile to log all environment modifications, such as installed packages or modified config files.
Sources: packages/mom/src/agent.ts:251-348
coding-agent Prompt
The coding-agent dynamically adjusts its system prompt based on the tools enabled, reinforcing a "least privilege" operational model.
- Read-Only Mode: If
bash,edit, andwritetools are disabled, the prompt explicitly states: "You are in READ-ONLY mode". - Tool Preferences: If
grep,find, orlstools are available alongsidebash, the prompt instructs the agent to prefer the dedicated tools for file exploration as they are faster and respect.gitignore.
Sources: packages/coding-agent/src/main.ts:400-450
Conclusion
The pi-mono project implements a comprehensive, defense-in-depth security strategy. It combines robust backend isolation using Docker (mom), secure frontend code execution via sandboxed iframes (web-ui), and explicit, context-aware instructions at the prompt level (coding-agent, mom). This layered approach allows the agents to perform powerful tasks while establishing clear security boundaries to protect the user's system and data from accidental or malicious behavior. The design acknowledges that no single layer is foolproof and relies on the combination of technical controls and agent guidance to create a safer operational environment.