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.

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?

The performance impact is minimal for most workloads, typically less than 2µs per checked syscall.

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?

Feature	Ash	Seatbelt	VM
File control	Allow paths & operations		Isolated
Process control	Allow paths & arguments	Allow paths	Isolated
Network control	Allow hosts, ports, etc.	Allow raw IP addresses	Network namespaces
IO Device control	Yes	Yes	VM dependent
ENV control	Yes	No	Isolated
Policy Lifetime	Update dynamically	Set at start	Set at boot
Apple API Access	Yes	Yes	Depends on guest OS

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
IO device: Denied unless a matching class 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?

Check the logs: Ash logs every blocked action with the matching rule
```
ash logs
```

Test specific actions:

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

Use observe mode: Run without enforcement to see all actions
```
ash observe -- your-command
```

Can I have multiple policies?

Yes. Combine policies with 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
macOS version
Steps to reproduce
Relevant logs

How do I request features?

Email feature requests to support@ashell.dev