Troubleshooting

This guide covers common issues and their solutions. If you don’t find your problem here, contact support@ashell.dev.

Installation Issues

”Ash” cannot be opened because it is from an unidentified developer

Cause: macOS Gatekeeper is blocking the app because it was downloaded from the web.

Solution:

  1. Right-click (or Control-click) on Ash.app in Finder
  2. Select Open from the context menu
  3. Click Open in the confirmation dialog
  4. The app will now open and be allowed in the future

Background application not enabled

Symptoms: Ash doesn’t seem to be running, or sandbox rules aren’t being enforced.

Solution:

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

If “Ash” doesn’t appear in the list:

  1. Try quitting and relaunching Ash.app
  2. Check System Settings > Privacy & Security for any pending approval notifications
  3. Try reinstalling Ash

Network Extension not activating

Symptoms: Network rules aren’t being enforced, connections to blocked hosts succeed.

Solution:

  1. Open 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

If “Ash” doesn’t appear in Network Extensions:

  • Relaunch Ash.app
  • Check for any pending system notifications
  • Try reinstalling Ash

Policy Issues

Policy not loading

Symptoms: Error message about policy file not found or invalid.

Diagnostics:

# Check if file exists
ls -la policy.yml

# Validate policy syntax
ash check --policy policy.yml

Common causes:

  • Typo in file path
  • YAML syntax errors (wrong indentation, missing colons)
  • Invalid policy structure

Rules not matching as expected

Symptoms: Actions are allowed/blocked when they shouldn’t be.

Diagnostics:

# See the fully expanded policy
ash expand --policy policy.yml

# Test specific decisions
ash test file --policy policy.yml read /path/to/file
ash test network --policy policy.yml example.com:443

Common causes:

  • A more specific rule is overriding yours (highest precedence wins)
  • Glob patterns not matching as expected
  • Variables not expanding correctly

Variable expansion issues

Symptoms: Paths with $HOME or $CWD aren’t matching.

Solution: Use ash expand to see actual expanded values:

ash expand --policy policy.yml

Make sure:

  • Variables use $ prefix (not ${VAR} syntax)
  • Supported variables are: $HOME (or ~), $CWD (or .), $USER, $ASH_SESSION_ID

Registry policy not found

Symptoms: Error like “policy not found: ash://…”

Diagnostics:

# Check network connectivity
curl -I https://registry.ashell.dev

# Verify the policy exists
ash info base-macos

Solutions:

  • Check spelling of policy name
  • Verify you have internet access
  • Clear cache and retry: rm -rf ~/.ash/cache/policies/
  • Check if the registry is down: status.ashell.dev

Runtime Issues

Ash isn’t blocking anything

Symptoms: You’re running a command through Ash but it seems to have full access to everything.

Diagnostics:

# Check the policy is valid
ash check --policy policy.yml

# Verify the expanded rules
ash expand --policy policy.yml

Common causes:

  • Using ash observe instead of ash run (observe mode allows everything)
  • Rules are too permissive (e.g., path: /** allows all files)
  • A dependency is granting broader access than expected

Solutions:

  1. Make sure you’re using ash run, not ash observe
  2. Check ash expand output to see the effective rules
  3. Review dependencies to see what they’re allowing

Legitimate actions being blocked

Symptoms: Your program fails because Ash blocks a necessary action.

Diagnostics:

# Run with verbose logging
ash run --verbose --policy policy.yml -- your-command

# Check what rule matched
# Look for lines like: [DENY] read /path/to/file (rule: line 15)

Solution: Update your policy to allow the action:

files:
  rules:
    - path: /path/that/was/blocked
      operations: [read] # or omit for all operations

Process hangs or crashes

Symptoms: Sandboxed process stops responding or crashes unexpectedly.

Diagnostics:

# Check Ash daemon logs
log show --predicate 'subsystem == "xyz.alexshapiro.ash"' --last 5m

# Run with verbose output
ash run --verbose --policy policy.yml -- your-command

Common causes:

  • Process waiting for blocked network connection (add timeout handling)
  • Deadlock in policy evaluation (report as bug)
  • Incompatible process using unsupported system calls

Child processes not sandboxed

Symptoms: Subprocess seems to bypass policy rules.

Verification:

# Check process tree is sandboxed
ash run --policy policy.yml -- bash -c 'ash status'

All child processes should show as sandboxed. If not, please report a bug to security@ashell.dev.

Performance issues

Symptoms: Sandboxed processes run significantly slower.

Diagnostics:

# Benchmark without sandbox
time your-command

# Benchmark with sandbox
time ash run --policy policy.yml -- your-command

Solutions:

  • Check for extreme numbers of file calls with ash logs
  • Report >10% overhead as a bug

Logging and Debugging

Collecting logs for bug reports

# 1. Run with verbose output
ash run --verbose --policy policy.yml -- your-command

# 2. Collect system logs
log show --predicate 'subsystem BEGINSWITH "xyz.alexshapiro.ash"' --last 10m > system.log

# 3. Include logs in your bug report

Understanding log output

Log format:

[timestamp] [level] [component] message

Key components:

  • daemon: Main Ash daemon
  • es: Endpoint Security events
  • ne: Network Extension events
  • policy: Policy evaluation

Example log entries:

[2024-01-15 10:30:45] [INFO] [es] Evaluating: read /etc/passwd
[2024-01-15 10:30:45] [DEBUG] [policy] Checking rule: path=/etc/** action=deny
[2024-01-15 10:30:45] [DEBUG] [policy] Rule matched, action=deny
[2024-01-15 10:30:45] [INFO] [es] DENY read /etc/passwd

Viewing real-time logs

# In one terminal, watch logs
log stream --predicate 'subsystem BEGINSWITH "xyz.alexshapiro.ash"'

# In another terminal, run your command
ash run --policy policy.yml -- your-command

Resetting Ash

If Ash is in a broken state, you can reset it:

Soft reset (clear cache and config)

rm -rf ~/.ash

Full reset (remove everything)

# 1. Quit Ash
osascript -e 'quit app "Ash"'

# 2. Remove app data
rm -rf ~/.ash
rm -rf ~/Library/Application\ Support/Ash
rm -rf ~/Library/Caches/xyz.alexshapiro.ash

# 3. Disable extensions in System Settings
# Go to System Settings > General > Login Items & Extensions
# Disable Ash under Background Applications and Network Extensions

Getting Help

If none of these solutions work:

  1. Check the FAQ: /docs/faq for general questions
  2. Email support: support@ashell.dev with:
    • Ash version (ash --version)
    • macOS version
    • Steps to reproduce
    • Debug logs (see above)
    • Policy file (if not sensitive)