happy sandbox

The happy sandbox command configures OS-level sandboxing to restrict AI agents’ file system and network access, providing an additional security layer.

Syntax

happy sandbox <subcommand>

Subcommands

configure

Interactively configure sandbox settings.

happy sandbox configure

Launches an interactive wizard to set up sandboxing options.

status

Display current sandbox configuration.

happy sandbox status

Shows whether sandboxing is enabled and current settings.

disable

Disable sandboxing completely.

happy sandbox disable

Turns off OS-level sandboxing (sessions will run unrestricted).

Description

Happy’s sandbox provides OS-level isolation for AI agents:

File access control: Restrict read/write to specific directories
Network restrictions: Block or allow network access
Process isolation: Prevent access to sensitive system resources
Per-session override: Bypass sandbox with --no-sandbox flag

Sandboxing is platform-specific. Features and restrictions may vary by OS.

Configuration Options

Scope Mode

Controls the breadth of file system access:

workspace

scope

AI agent can access entire workspace root directoryBest for: Monorepos, workspace-wide operationsExample: Allow access to ~/Workspace/*

per-project

scope

AI agent restricted to current project directory onlyBest for: Maximum isolation, sensitive projectsExample: Only allow access to current directory

Network Mode

allowed

network

Allow all network access (default)Use when: Agent needs to install packages, fetch data, make API calls

blocked

network

Block all network access (most secure)Use when: Working with sensitive data, offline developmentNote: May break package installation and API features

Localhost Binding

allowLocalBinding

boolean

Allow binding to localhost ports (enabled by default)Required for: Development servers, local testingExample: Running npm start, python -m http.server

Examples

Initial Configuration

happy sandbox configure

Interactive wizard:

? How should file access be scoped?
  ❯ workspace - Full workspace root directory
    per-project - Only current project directory

? Pick your workspace root directory
  ❯ ~/Workspace
    ~/Developer (suggested)
    ~/Develop

? How should network access be handled?
  ❯ allowed - Allow all network access (default)
    blocked - Block all network access (most secure)

? Allow binding to localhost ports? (for dev servers) (Y/n)

Sandbox configuration summary:
{
  "enabled": true,
  "workspaceRoot": "~/Workspace",
  "sessionIsolation": "workspace",
  "customWritePaths": [],
  "denyReadPaths": ["~/.ssh", "~/.aws", "~/.gnupg"],
  "extraWritePaths": ["/tmp"],
  "denyWritePaths": [".env"],
  "networkMode": "allowed",
  "allowedDomains": [],
  "deniedDomains": [],
  "allowLocalBinding": true
}

? Save and enable this sandbox configuration? (Y/n)

✓ Sandbox configuration saved and enabled.
Use --no-sandbox to bypass sandboxing for a single session.

Check Current Status

happy sandbox status

Output when enabled:

Sandbox status
Enabled: yes
Scope: workspace
Workspace root: ~/Workspace
Network mode: allowed
Allow localhost binding: yes

Output when not configured:

Sandbox is not configured. Run `happy sandbox configure`.

Disable Sandboxing

happy sandbox disable

Output:

✓ Sandbox disabled.

Per-Session Bypass

Run a single session without sandbox:

happy --no-sandbox

Configuration File

Sandbox settings are stored in:

~/.happy/settings.json (production)
~/.happy-dev/settings.json (development)

Example Configuration

{
  "sandboxConfig": {
    "enabled": true,
    "workspaceRoot": "~/Workspace",
    "sessionIsolation": "workspace",
    "customWritePaths": [],
    "denyReadPaths": [
      "~/.ssh",
      "~/.aws",
      "~/.gnupg"
    ],
    "extraWritePaths": ["/tmp"],
    "denyWritePaths": [".env"],
    "networkMode": "allowed",
    "allowedDomains": [],
    "deniedDomains": [],
    "allowLocalBinding": true
  }
}

Field Descriptions

enabled

boolean

Master switch for sandboxing

workspaceRoot

string

Root directory for workspace scope mode

sessionIsolation

string

Isolation mode: workspace or strict (per-project)

denyReadPaths

string[]

Paths that should never be read by AI agentDefault: ~/.ssh, ~/.aws, ~/.gnupg (sensitive credentials)

extraWritePaths

string[]

Additional paths where agent can writeDefault: /tmp (for temporary files)

denyWritePaths

string[]

Files that should never be written by agentDefault: .env (environment variables)

networkMode

string

Network access mode: allowed or blocked

allowLocalBinding

boolean

Whether agent can bind to localhost ports

Protected Paths

Default Read Restrictions

The following paths are blocked from reading by default:

~/.ssh/ - SSH keys and certificates
~/.aws/ - AWS credentials
~/.gnupg/ - GPG keys

Default Write Restrictions

The following files are blocked from writing:

.env files - Environment variables and secrets

Allowed Write Paths

By default, agents can write to:

Workspace directory (if in workspace mode)
Current project directory
/tmp/ - Temporary files

Use Cases

Maximum Security

For sensitive projects:

happy sandbox configure
# Select:
# - Scope: per-project
# - Network: blocked
# - Localhost: no

This restricts the agent to:

Current directory only
No network access
No port binding

Development-Friendly

For typical development:

happy sandbox configure
# Select:
# - Scope: workspace
# - Network: allowed
# - Localhost: yes

This allows:

Full workspace access
Network for packages/APIs
Development servers

Monorepo

For large monorepo projects:

happy sandbox configure
# Select workspace mode with your monorepo root
# workspaceRoot: ~/code/my-monorepo

Agent can access all packages/apps within the monorepo.

Permission Modes vs Sandbox

Sandbox and permission modes are complementary security layers:

Permission modes: Control what operations the AI attempts
Sandbox: Enforces OS-level restrictions on what’s possible

Example: Bypass Permissions in Sandbox

happy --yolo  # Bypass permission prompts

Even with --yolo, the sandbox still prevents:

Reading ~/.ssh/
Writing .env files
Accessing paths outside workspace (if configured)

Troubleshooting

Agent Can’t Access Files

If agent reports permission denied:

# Check sandbox status
happy sandbox status

# Temporarily disable
happy --no-sandbox

# Or reconfigure
happy sandbox configure

Package Installation Fails

If network-based operations fail:

# Check network mode
happy sandbox status

# Run without sandbox for this session
happy --no-sandbox

# Or reconfigure to allow network
happy sandbox configure  # Select "allowed" for network

Dev Server Won’t Start

If localhost binding fails:

# Reconfigure to allow localhost
happy sandbox configure
# Enable: "Allow binding to localhost ports"

# Or bypass for this session
happy --no-sandbox

Monorepo Access Issues

If agent can’t access other packages in monorepo:

# Reconfigure with correct workspace root
happy sandbox configure
# Set workspaceRoot to your monorepo root
# Example: ~/code/my-monorepo

Reset Configuration

# Disable current config
happy sandbox disable

# Start fresh
happy sandbox configure

Platform Support

macOS

✅ File system restrictions
✅ Network restrictions
✅ Process isolation
Uses macOS sandbox profiles

Linux

✅ File system restrictions
✅ Network restrictions
✅ Process isolation
Uses seccomp-bpf or similar

Windows

⚠️ Limited support
May not enforce all restrictions
Use with caution

Sandbox implementation is platform-specific. Test your configuration before relying on it for security.

Best Practices

For Sensitive Projects

Use per-project scope
Block network access
Review denyReadPaths
Add sensitive files to denyWritePaths

For General Development

Use workspace scope
Allow network (for packages)
Enable localhost binding
Keep default restrictions

For CI/CD

# Disable sandbox in CI environments
export HAPPY_SANDBOX_DISABLED=true
happy --no-sandbox

happy - Uses sandbox when enabled
happy codex - Respects sandbox configuration
happy gemini - Sandboxed by default
happy doctor - Check sandbox status

Sandboxing adds an important security layer but may restrict legitimate operations. Start with workspace mode and allowed network, then tighten as needed.

Commands

Configuration

Documentation Index

​Syntax

​Subcommands

​configure

​status

​disable

​Description

​Configuration Options

​Scope Mode

​Network Mode

​Localhost Binding

​Examples

​Initial Configuration

​Check Current Status

​Disable Sandboxing

​Per-Session Bypass

​Configuration File

​Example Configuration

​Field Descriptions

​Protected Paths

​Default Read Restrictions

​Default Write Restrictions

​Allowed Write Paths

​Use Cases

​Maximum Security

​Development-Friendly

​Monorepo

​Permission Modes vs Sandbox

​Example: Bypass Permissions in Sandbox

​Troubleshooting

​Agent Can’t Access Files

​Package Installation Fails

​Dev Server Won’t Start

​Monorepo Access Issues

​Reset Configuration

​Platform Support

​macOS

​Linux

​Windows

​Best Practices

​For Sensitive Projects

​For General Development

​For CI/CD

​Related Commands

Build docs developers (and LLMs) love

Syntax

Subcommands

configure

status

disable

Description

Configuration Options

Scope Mode

Network Mode

Localhost Binding

Examples

Initial Configuration

Check Current Status

Disable Sandboxing

Per-Session Bypass

Configuration File

Example Configuration

Field Descriptions

Protected Paths

Default Read Restrictions

Default Write Restrictions

Allowed Write Paths

Use Cases

Maximum Security

Development-Friendly

Monorepo

Permission Modes vs Sandbox

Example: Bypass Permissions in Sandbox

Troubleshooting

Agent Can’t Access Files

Package Installation Fails

Dev Server Won’t Start

Monorepo Access Issues

Reset Configuration

Platform Support

macOS

Linux

Windows

Best Practices

For Sensitive Projects

For General Development

For CI/CD

Related Commands