Isolate Bob Shell operations in a secure sandbox environment to protect your host system.

Sandboxing isolates potentially dangerous operations, such as shell commands or file modifications, from your host system.

Why use sandboxing?

Sandboxing provides several key benefits:

Isolation: Limits file system access to your project directory only
Consistency: Ensures reproducible environments across different systems
Safety: Reduces risk when experimenting with untrusted code or commands

Sandboxing methods

Choose from the following options to create a sandbox environment:

macOS Seatbelt (macOS only)

You can use the default sandbox-exec utility.

Default profile: permissive-open - restricts writes outside your project directory while allowing most other operations.

Container-based (Docker/Podman)

Cross-platform sandboxing with complete process isolation using Docker or Podman containers.

Note:

Container-based sandboxing requires building the sandbox image locally or using a published image from your organization's registry.

Configuration

You can enable sandboxing through command flags, environment variables, or configuration files.

Enable sandboxing for a single command using the -s or --sandbox flag. Use command flags for one-time testing or when you need sandboxing for a specific command without affecting your default workflow.

bob -s "analyze this shell script for potential security issues before execution"

Environment variables

Set the BOB_SHELL_SANDBOX environment variable. Use environment variables when you want sandboxing enabled for an entire terminal session or specific project without modifying configuration files.

export BOB_SHELL_SANDBOX=true
bob "analyze this shell script for potential security issues before execution"

You can also specify the sandbox type:

export BOB_SHELL_SANDBOX=docker  # or podman, or sandbox-exec

Settings file

Add the sandbox option to the tools object in your settings.json. Use the settings file for persistent, project-wide sandboxing that applies to all team members and sessions.

{
  "tools": {
    "sandbox": true
  }
}

You can also use a specific sandbox type:

{
  "tools": {
    "sandbox": "docker"
  }
}

Configuration precedence (highest to lowest):

Command flag (-s or --sandbox)
Environment variable (BOB_SHELL_SANDBOX)
Settings file (settings.json)

macOS Seatbelt profiles

Control the level of restriction using the SEATBELT_PROFILE environment variable:

Profile	Network	Write access	Use case	When to use
`permissive-open` (default)	Allowed	Project only	General development	Everyday development work where you need network access and reasonable security without significant restrictions.
`permissive-closed`	Blocked	Project only	Offline work	Working offline or in environments where network access should be blocked, but you still need full project directory access.
`permissive-proxied`	Via proxy	Project only	Corporate environments	Corporate environments where all network traffic must route through a proxy server. Best for enterprise settings with strict network policies.
`restrictive-open`	Allowed	Strict limits	High security	High security with network access, but strict file system limitations beyond the project directory. Ideal for working with potentially malicious code that needs internet access.
`restrictive-closed`	Blocked	Maximum restrictions	Maximum security	Maximum security. Use when working with untrusted or potentially dangerous code that requires complete isolation from your network and file system.

Example:

export SEATBELT_PROFILE=restrictive-open
bob -s "analyze this shell script for potential security issues before execution"

Custom sandbox flags

For container-based sandboxing, inject custom flags into the docker or podman command using the SANDBOX_FLAGS environment variable. Use this when you need more control over container resources, security settings, or volume mounts, best for advanced users who need to customize memory limits, CPU allocation, or SELinux configurations for specific workloads.

Single flag example:

export SANDBOX_FLAGS="--security-opt label=disable"
bob -s "analyze this shell script for potential security issues before execution"

Multiple flags example:

export SANDBOX_FLAGS="--memory=4g --cpus=2"
bob -s "analyze this shell script for potential security issues before execution"

This is useful for:

Disabling SELinux labeling on Podman.
Setting resource limits.
Configuring network settings.
Adding custom volume mounts.

Linux UID/GID handling

Bob Shell automatically handles user permissions on Linux to ensure files created in the sandbox have the correct ownership. Use this to control file ownership mapping between the container and host system, best for Linux environments where you need to ensure files created in the sandbox have correct permissions or when troubleshooting permission issues.

Override this behavior if needed:

# Force host UID/GID mapping
export SANDBOX_SET_UID_GID=true

# Disable UID/GID mapping
export SANDBOX_SET_UID_GID=false

Limitations

While sandboxing significantly improves security, it has some important limitations to be aware of:

General:

Not a complete security solution: Sandboxing reduces but doesn't eliminate all risks. Always review Bob's actions before approval.
Performance overhead: Container-based sandboxing has minimal overhead after the initial build, but operations may be slightly slower than native execution.
GUI applications: Graphical applications typically won't work inside sandboxes due to display isolation.

File system:

Project directory only: By default, only your current project directory is accessible inside the sandbox.
Symbolic links: Symlinks pointing outside the project directory may not work correctly.
File permissions: Permission issues may occur with files created inside the sandbox, especially on Linux.

Network:

Restricted profiles: Some Seatbelt profiles (permissive-closed, restrictive-closed) block all network access.
Localhost services: Services running on your host machine may not be accessible from inside container sandboxes without additional configuration.
VPN connections: Container sandboxes may not have access to VPN-connected resources.

Tools and commands:

Missing tools: The sandbox environment may not have all tools installed that are available on your host system. You can add tools via custom Dockerfile or sandbox.bashrc.
System commands: Commands that require system-level access (e.g., sudo, system service management) won't work in sandboxes.
Hardware access: Direct hardware access (USB devices, GPUs, etc.) is typically not available in sandboxes.

macOS Seatbelt:

macOS only: Seatbelt sandboxing only works on macOS systems.
Less isolation: Provides less isolation than container-based approaches.
Profile restrictions: Some operations may be blocked depending on the chosen profile.

Sandboxing