Runtime Sandbox Policy

Sandbox policies let you control what agents can access and do while running on a daemon. You can restrict filesystem paths, block dangerous commands, limit network connections, and optionally run agents in isolated containers.

Why sandboxing matters

Agents are powerful — they can read files, execute commands, and make network requests. Without sandboxing:

• Data leaks — an agent could read SSH keys, AWS credentials, or other sensitive files
• System damage — an agent could delete important files or execute dangerous commands
• Supply chain attacks — a compromised skill could exfiltrate data or pivot to other systems
• Regulatory violations — some compliance frameworks require workload isolation

Sandbox policies prevent these risks by enforcing boundaries.

Sandbox policy components

A sandbox policy controls four aspects:

Filesystem access

Allow list — paths (and subpaths) that agents can read and write:

/home/user/workspace
/tmp
/var/tmp

Deny list — paths that are always blocked, even if in the allow list:

~/.ssh
~/.aws
~/.gnupg
/etc

By default, AACWorkflow denies access to credential directories and system config. You can add more denials, but you cannot remove the built-in deny list.

Command execution

Allow list — if set, only these commands can run. Empty = no restriction.

git
grep
python

Deny list — commands/patterns that are always blocked:

rm -rf /
chmod 777
curl | sh

Denied commands fail immediately with an audit entry.

Network access

Allow list — hostnames and CIDR blocks that agents can connect to:

github.com
api.openai.com
10.0.0.0/8

Deny list — always-blocked hosts and patterns:

169.254.169.254  (AWS metadata)
127.0.0.1:22  (local SSH)

Default behavior depends on your runtime's network policy.

Executor type

• Local — agent runs directly on the daemon OS (default, lightweight)
• Container — agent runs in an isolated rootless container (more secure, requires Docker/Podman)

Creating a sandbox policy

Sandbox policies are configured at the workspace level, not per-agent.

1. Go to Settings → Security → Sandbox Policy
2. Review the default policy (already set, shows denials for credential directories)
3. Add filesystem allowlist — paths your agents should access
4. Add filesystem denials — paths to explicitly block (beyond defaults)
5. Add command restrictions (optional) — allowlist or denylist
6. Add network restrictions (optional) — allowlist or denylist
7. Choose executor type — local or container
8. Click Save

Filesystem permissions in detail

Allow list (what agents can access)

Agents can read and write paths that match an allow-list entry:

FilesystemAllow:
  - /home/user/workspace    # Agents can access this dir and subdirs
  - /tmp                     # Agents can use /tmp
  - /var/data               # Agents can access /var/data

The per-task working directory is always allowed, regardless of policy.

Deny list (what agents cannot access)

Deny entries always block, even if a broader allow entry includes them:

FilesystemDeny:
  - ~/.ssh                  # Deny SSH keys
  - ~/.aws                  # Deny AWS credentials
  - ~/.gnupg               # Deny GPG keys
  - /etc                    # Deny system config (built-in default)

Built-in denials (cannot be removed):

• ~/.ssh — SSH keys
• ~/.aws — AWS credentials
• ~/.gnupg — GPG private keys
• ~/.config/gh — GitHub CLI config
• /etc — System configuration
• AACWorkflow daemon config directory

You can add more to this list, but you cannot remove the built-in entries.

Command restrictions in detail

Allow list (command whitelist)

If you set an allow list, only commands in the list can run:

CommandAllow:
  - git          # Agents can run 'git'
  - grep         # Agents can run 'grep'
  - python       # Agents can run 'python'
  - python3      # Agents can run 'python3'

Any other command fails with an error.

If the allow list is empty, all commands are allowed (unless blocked by deny list).

Deny list (command blacklist)

Commands in the deny list never run:

CommandDeny:
  - rm -rf /         # Block destructive deletes
  - chmod 777        # Block permission changes
  - curl | sh        # Block download-and-execute
  - sudo             # Block privilege escalation
  - :(){ :|:& };:    # Block fork bombs

When a denied command is attempted:

• Execution fails with a clear error
• An audit entry is logged
• The agent is notified and can try a different approach

Built-in deny patterns

AACWorkflow includes built-in deny patterns for known-dangerous commands:

• File deletion: rm -rf, dd if=/dev/zero
• Privilege changes: chmod 777, chown, sudo
• Git history tampering: git push --force to main/master
• Shell bombs: :(){ :|:& };:
• Remote code execution: curl | sh, wget -qO- | sh
• Reverse shells: Netcat, reverse-shell signatures

You can add more patterns without removing built-ins.

Network restrictions in detail

Allow list (approved destinations)

Agents can connect to hostnames and networks in the allow list:

NetworkAllow:
  - github.com              # Agents can connect to GitHub
  - api.openai.com          # Agents can call OpenAI
  - 10.0.0.0/8              # Agents can reach 10.x.x.x
  - "*.internal.example.com" # Agents can reach *.internal

Deny list (blocked destinations)

Agents cannot connect to these hostnames/networks:

NetworkDeny:
  - 169.254.169.254  # AWS EC2 metadata service
  - 127.0.0.1:22     # Local SSH
  - 0.0.0.0/0        # Block all (if combined with allow list)

Denied connections are blocked at the socket level and audited.

Container executor (advanced)

For maximum isolation, you can run agents inside rootless containers:

1. Go to Settings → Security → Sandbox Policy
2. Under Executor, select Container
3. Optionally configure container-specific settings:
   • Memory limit (e.g., 2 GB)
   • CPU limit (e.g., 2 cores)
   • Network mode (isolated by default)
4. Click Save

Prerequisites:

• Docker or Podman must be installed on the daemon
• The daemon process must have permission to create containers
• Rootless mode is recommended (safer than running with root)

What happens:

• Agent's task runs inside a container
• Per-task working directory is bind-mounted
• File permissions from sandbox policy are enforced
• Network is isolated per NetworkAllow
• Each container is deleted after the task completes

Trade-offs:

• Pros: True isolation, dropped Linux capabilities, read-only root filesystem
• Cons: Slight performance overhead, requires container runtime, more complex debugging

Viewing the effective policy

On the Settings page, you can see:

• Built-in defaults — what AACWorkflow enforces by default
• Your overrides — what you've added or customized
• Effective policy — the merged result

Example:

Built-in deny:  ~/.ssh, ~/.aws, /etc
Your additions: /root/.kube, ~/confidential
Effective deny: ~/.ssh, ~/.aws, /etc, /root/.kube, ~/confidential

Auditing sandbox violations

All sandbox policy violations are logged:

• Path access denials
• Command execution failures
• Network connection blocks

View the audit log in Settings → Audit Logs and filter by "Sandbox" or "Security" to see:

• When and which agent tried to access a denied path
• What commands were blocked and why
• Which network connections were denied

Use these logs to:

• Adjust policies if agents legitimately need access
• Investigate suspicious behavior
• Comply with audit requirements

Best practices

• Start restrictive — deny by default, allow what's needed
• Use container executor — for untrusted or high-risk tasks
• Review denials regularly — if agents hit deny rules, investigate
• Pair with threat detection — sandbox policy + threat detection together
• Document your allowlists — share with your team why certain paths/commands are needed
• Test before production — enable policies on a test runtime first

Limitations

• Local mode is best-effort — sandboxing on the host OS relies on OS-level protections, which can sometimes be bypassed
• Cannot remove built-in denials — credential directories are always protected
• Container mode requires runtime — you need Docker or Podman installed
• Network allowlist is exact — wildcard patterns have limited support; use IP ranges for broad targets

Next steps

• Threat detection checks — active scanning for suspicious behavior
• Secrets isolation (Enterprise) — manage credentials securely
• Approval policies — require review for sensitive changes