Tutorial

This tutorial walks you through sandboxing an AI coding agent with Ash. By the end, you'll understand how to write policies and run agents securely.

Prerequisites

  • Ash installed and configured (see Installing Ash)
  • AI coding agent (we'll use Claude Code as an example)

Step 1: Create a Project Directory

Create a project directory:

mkdir -p ~/projects/chowderbot
cd ~/projects/chowderbot

Step 2: Initialize Your Policy

Create a policy file:

ash init

The file is saved to .ash/policy.yml.

Step 3: Edit Your Policy

Add rules to the policy based on your needs:

# Pre-built policy dependencies
dependencies:
  ash/base-macos: "^1.0"   # Basic macOS permissions
  ash/claude-code: "^1.0"  # Claude Code
  ash/git: "^1.0"          # git version control
  ash/python-dev: "^1.0"   # Python dev tooling

# Filesystem access rules
files:
  rules:
    # All access to the current project directory
    - path: ./**

# Network access rules
network:
  rules:
    - host: '*.chowderbot.test'
      ports:
      - 443
    - host: ci.my-buildserver.tld
      ports:
      - 443
    - host: git.my-buildserver.tld
      ports:
      - 22

# Process execution rules
exec:
  rules:
    # Project-specific processes
    - path: alembic-helper
    - path: ./scripts/**
    # Deny dangerous rm commands
    - path: rm
      args:
        - flag: -f
        - flag: --force
        - positional: /
        - positional: ~
      action: deny

# Environment variables
environment:
  rules:
    allow:
      - CHOWDERBOT_MAILER_KEY
      - CHOWDERBOT_DATABASE_URL

Step 3: Run the Agent in the Sandbox

Use ash run to launch your AI agent with the policy:

ash run -- claude

The agent now runs inside the sandbox. All file operations, network connections, and process executions are monitored and filtered according to your policy.

Step 4: Test the Sandbox

While the agent is running, try some actions to see the sandbox in effect:

Allowed actions

These should work normally:

  • Reading and writing files in ~/projects/chowderbot
  • Making API calls to your AI provider
  • Running git commands

Blocked actions

These should be blocked by the sandbox:

  • Attempting to read your photos ls ~/Pictures
  • Connecting to arbitrary external hosts curl http://kremlin.ru
  • Deleting all of your data rm -rf /

Step 5: Observe Mode (Optional)

To build up a policy without explicitly writing rules, use observe mode:

ash observe -- claude

Observation is allow by default: all actions are allowed unless explicitly denied. Whenever an unknown action is observed, Ash adds it to the policy file.

Once you have built up a profile of typical agent requirements, switch back to run mode.

Next Steps

Now that you've sandboxed your first agent, explore these topics: