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 in your Applications directory, you will need to grant a few system permissions before the sandbox functions properly. The Ash application's Setup tab will guide you through the process of:

  • creating an ash symlink for the Ash command line tool
  • letting Ash run in the background (for file, io_device, and exec rules)
  • letting Ash filter network traffic (for network rules)
  • letting Ash send notifications (optional, but useful)

In the Setup > CLI Symlink section of the Ash app, press the "Link" button and authenticate to create an ash symlink for the Ash command line tool.

Background Services

In the Setup > Background Services section of the Ash app, press the "Enable" button and authenticate to give Ash permission to run as a background process.

The ash-daemon background process runs all sandbox logic for intercepting syscalls related to files, IO devices, and process execution. If the background process is not running, Ash will refuse to start a sandbox session.

If the in-app permission flow fails, you can manually enable the background process in Settings:

  1. Open the System Settings app
  2. Navigate to General > Login Items & Extensions
  3. Under Allow in the Background, find "Ash"
  4. Toggle the switch to "on"
  5. Enter your password to confirm

Network Extension

In the Setup > Network Filter section of the Ash app, press the "Enable" button and authenticate to give Ash permission to filter network traffic. Then do the same in the Setup > Network Extension section.

The AshNetworkExtension process runs all sandbox logic for intercepting syscalls related to network connections. If the network extension is not running, Ash will refuse to start a sandbox session.

If the in-app permission flow fails, you can manually enable in Settings:

  1. Open the System Settings app
  2. In System Settings > General > Login Items & Extensions
  3. Click on Network Extensions
  4. Find "Ash" and toggle the switch to "on"
  5. Enter your password to confirm

Verifying Installation

After completing the setup, verify Ash is working correctly by checking its status

$ ash status
Version: 0.1.0
Endpoint Security: ✓
Network Filter: ✓
Network Extension: ✓

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 enabled

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

Network extension is enabled but not active

In rare cases, a network extension may be enabled but not active because the operating system is running a different version of the extension. When this happens, the OS requires a reboot before the updated network extension will run.

For more help, see the Troubleshooting guide.