Installing Ash

This guide walks you through installing Ash on your Mac and configuring the required system permissions.

System Requirements

  • macOS: 15.0 (Sequoia) or later
  • Architecture: Apple Silicon or Intel (Universal binary)
  • Disk space: Approximately 30 MB

Installation Methods

Download from Website

  1. Visit the download page
  2. Click Download for macOS to get the latest version
  3. Open the downloaded Ash.app.zip file
  4. Drag Ash.app to your Applications folder

Using Homebrew (Coming Soon)

brew install --cask ash

Post-Installation Setup

After installing Ash.app, you need to grant two system permissions for Ash to function correctly. Both are configured in System Settings > General > Login Items & Extensions.

1. Background Applications

When you first launch Ash, macOS will prompt you to allow it to run in the background:

  1. Click Open System Settings when prompted
  2. Navigate to General > Login Items & Extensions
  3. Under Allow in the Background, find “Ash”
  4. Toggle the switch to enable it
  5. Enter your password to confirm

2. Network Extension

Ash uses a Network Extension to filter network connections:

  1. In System Settings > General > Login Items & Extensions
  2. Click on Network Extensions
  3. Find “Ash” and toggle the switch to enable it
  4. Enter your password to confirm

macOS may show a notification about adding a network filter. This is normal. Ash uses the network filter System Extension to sandbox network connections.

Verifying Installation

After completing the setup, verify Ash is working correctly:

# Check that ash CLI is available
ash --version

# Run a simple test
ash run --policy /dev/null -- echo "Hello from sandbox"

If both commands succeed, Ash is installed and configured correctly.

Troubleshooting

Ash cannot be opened because it is from an unidentified developer

This happens when downloading from the web. To resolve:

  1. Right-click (or Control-click) on Ash.app
  2. Select Open from the context menu
  3. Click Open in the confirmation dialog

Background application not enabled

If Ash isn’t running properly:

  1. Open System Settings > General > Login Items & Extensions
  2. Under Allow in the Background, make sure “Ash” is enabled
  3. If it’s not listed, try relaunching Ash.app

Network extension not activating

If network filtering isn’t working:

  1. Open System Settings > General > Login Items & Extensions
  2. Click on Network Extensions
  3. Make sure “Ash” is enabled
  4. If it’s not listed, try reinstalling Ash

For more help, see the Troubleshooting guide.