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.

4 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 install nono

From source (requires Rust toolchain):

bash
cargo build --release

Verify the installation:

bash
nono --version

Choose or create a profile

A profile defines the filesystem, network, and command access rules for a sandbox. The fastest way to get a hardened, signed profile for a specific agent is to install a pack from the nono registry.

Search the registry for a pack:

bash
nono search claude

Install a pack. This pulls the signed pack and registers its profile — for example, always-further/claude provides the claude-code profile:

bash
nono pull always-further/claude

Add --init to also copy the pack's project instructions into the current directory:

bash
nono pull always-further/claude --init

List installed packs and the profiles available on your system:

bash
nono list --installed
nono profile list

nono profile list shows both registry-managed packs and the built-in profiles (default, python-dev, node-dev, rust-dev, and more). The 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 profile:

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

To create a custom profile, generate a skeleton that extends an existing one:

bash
nono profile init my-agent --extends claude-code

Edit the generated JSON to add or remove allowed paths, network domains, and commands, then validate it. See the profile reference for the full schema.

bash
nono profile validate my-agent
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 (when run with --rollback)

To allow network access to specific hosts:

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

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

Review the audit log

After the session ends, list recent sandboxed sessions:

bash
nono audit list

Then show what a given session did, using its ID:

bash
nono audit show <id>

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 show <id> --json

Undo if needed

If you ran the agent with --rollback and it made unwanted changes, restore the session. First list rollback sessions:

bash
nono rollback list

Then restore every file to its pre-session state using the SHA-256 content-addressed snapshot:

bash
nono rollback restore <id>

You can also review the diff before restoring:

bash
nono rollback show <id> --diff

Runtime supervision

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

bash
nono run --profile claude-code --capability-elevation -- 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