Guides/Safe AI Agent Execution with nono

Safe AI Agent Execution with nono

A complete guide to running AI coding agents with kernel-level isolation, network filtering, and runtime supervision.

3 min read

AI coding agents run as your user. They have the same access you do: SSH keys, cloud credentials, source code across every project on your machine. This guide walks through setting up nono to enforce kernel-level boundaries around agent execution.

Install nono

On macOS:

bash
brew tap always-further/nono && brew install nono

From source (requires Rust toolchain):

bash
cargo build --release

Verify the installation:

bash
nono --version

Choose or create a profile

nono ships with built-in profiles for common AI coding agents. List them:

bash
nono profiles list

Each profile is a JSON file defining filesystem, network, and command access rules. The built-in claude-code profile allows access to the current working directory and common development tools while blocking sensitive directories and unrestricted network access.

To use a built-in profile:

bash
nono run --profile claude-code -- claude

To create a custom profile, start from a built-in one and modify:

bash
nono profiles export claude-code > my-profile.json

Edit my-profile.json to add or remove allowed paths, network hosts, and commands. See the profile reference for the full schema.

Tip

Start with a restrictive profile and expand as needed. It is easier to add permissions than to audit what an overly permissive agent accessed.

Run your agent

The basic invocation wraps your agent command with nono:

bash
nono run --allow ~/projects/myapp -- claude

This creates a sandbox that:

  1. Allows read/write access to ~/projects/myapp and its subdirectories
  2. Blocks access to all other filesystem paths (including ~/.ssh, ~/.aws, ~/.config)
  3. Blocks all outbound network connections by default
  4. Records every operation in the audit trail
  5. Captures a filesystem snapshot before the agent starts

To allow network access to specific hosts:

bash
nono run \
  --allow ~/projects/myapp \
  --proxy-allow registry.npmjs.org \
  --proxy-allow api.github.com \
  -- claude
Warning

Never use --trust-unsigned in production. This flag bypasses instruction file verification and should only be used during initial setup.

Review the audit log

After the session ends, review what the agent did:

bash
nono audit --session latest

This shows every file read, file write, network connection attempt, and command execution. Violations (denied operations) are highlighted.

For a machine-readable format:

bash
nono audit --session latest --format json

Undo if needed

If the agent made unwanted changes, undo the entire session:

bash
nono undo latest

This restores every file to its pre-session state using the SHA-256 content-addressed snapshot. You can also review the diff before undoing:

bash
nono diff latest

Runtime supervision

For workflows that require dynamic permission expansion, enable the runtime supervisor:

bash
nono run --profile claude-code --supervisor terminal -- claude

When the agent tries to access a resource outside its sandbox, nono prompts you in the terminal. You can approve, deny, or approve-always for the session duration. All supervisor decisions are recorded in the audit trail.

Next steps