FAQ

General Questions

What is Ash?

Ash is a sandbox designed specifically for macOS. It uses system extensions (like kernel extensions, but running in userspace) to restrict AI agent access to your files, networks, processes, and environment variables.

How does Ash work?

Ash uses two macOS security frameworks:

• Endpoint Security (ES): Monitors and controls file operations, process execution, and other system events at the kernel level
• Network Extension (NE): Filters network connections before they’re established

When you run a command through Ash, these frameworks intercept all relevant system calls and check them against your policy before allowing them to proceed.

Is Ash open source?

No, Ash is proprietary software. Registry policies are open source (all 1P Ash-authored policies are MIT-licensed) but the core product is not.

What macOS versions are supported?

Ash requires macOS 15.0 (Sequoia) or later.

Does Ash work on Apple Silicon and Intel Macs?

Yes. Ash is distributed as a universal binary that runs natively on both Apple Silicon and Intel Macs.

Technical Questions

Can I use Ash with [specific agent]?

Ash works with any command line tool, including:

• Claude Code: Yes
• OpenAI Codex: Yes
• Gemini CLI: Yes
• OpenCode: Yes
• [OTHER]: Yes

If a tool runs from your terminal, Ash can sandbox it.

Does Ash affect system performance?

Performance impact is minimal for most workloads:

• File operations: 10µs-1ms overhead per file operation
• Network connections: Negligible overhead once established
• Process execution: One-time policy check per exec

Does Ash work with Docker or VMs?

Ash operates at the macOS level, so it can sandbox processes that manage Docker or VMs. However, Ash cannot see inside the container or VM. Processes inside the containers are not sandboxed.

Does Ash sandbox child processes?

Yes. When you run a process through Ash, all of its child processes (and their children, recursively) inherit the sandbox. This is crucial for AI agents, which often spawn subprocesses to run commands.

Can a sandboxed process escape the sandbox?

Ash uses kernel-level enforcement, making escape extremely difficult. The sandboxed process cannot:

• Disable or modify the policy
• Access files outside allowed paths
• Make network connections to blocked hosts
• Execute blocked commands

If you discover a sandbox escape, please report it to security@ashell.dev.

How does Ash compare to other sandboxing tools?

Policy Questions

How does Ash’s deny-by-default model work?

Ash policies are deny-by-default. If an action isn’t explicitly allowed by a rule (or a dependency), it’s denied.

• files: Denied unless a matching path rule exists
• network: Denied unless a matching host rule exists
• exec: Denied unless a matching path rule exists
• environment: Variables are filtered unless explicitly allowed

To allow something, add a rule for it:

network:
  rules:
    - host: allowed.example.com
    - host: "*.trusted.com"

How do I debug why something is blocked?

1. Check the logs: Ash logs every blocked action with the matching rule

   ash logs

2. Test specific actions:

   ash test file read /path/to/file
   ash test network example.com:443

3. Use observe mode: Run without enforcement to see all actions

   ash observe -- your-command

Can I have multiple policies?

You can combine policies using dependencies:

schema_version: 1

dependencies:
  base-macos: "1"
  git-dev: "1"
  local:
    - ./team-policy.yml

files:
  rules:
    # Additional rules...

Rules from all dependencies are merged using Ash’s precedence system.

Support

How do I report bugs?

Email us at support@ashell.dev with:

• Ash version (ash --version)
• macOS version
• Steps to reproduce
• Relevant logs (ash run --verbose ...)

How do I request features?

Email feature requests to support@ashell.dev. We read every request and prioritize based on user feedback.

Is there commercial support?

Contact sales@ashell.dev for enterprise support options.