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)
  • An AI coding agent (we’ll use Claude Code as an example)

Step 1: Create a Project Directory

Create a project directory:

mkdir ~/myproject
cd ~/myproject

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:
  base-macos: "^1.0" # policy for common macOS permissions
  claude-code: "^1.0" # policy for Claude Code
  git: "^1.0" # policy for git version control
  python-dev: "^1.0" # policy for common Python dev tools

# Filesystem access rules
files:
  rules:
    # Allow read-write access to the current project
    - path: ./**

# Network access rules
network:
  rules:
    - host: api.my-company.tld
    - host: ci.my-buildserver.tld

# 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:
      - MYPROJECT_MAILER_KEY
      - MYPROJECT_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 ~/myproject
  • 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: