> ## Documentation Index
> Fetch the complete documentation index at: https://nono.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Learn how to use nono to sandbox commands

nono wraps any command with an OS-level sandbox. You specify what the command is allowed to access, and nono enforces those restrictions at the kernel level.

## Your First Sandbox

```bash theme={null}
nono run --allow . -- <COMMAND> [ARGS...]
```

<Note>
  The `--` separator is used for visual clarity, to help the reader distinguish between nono flags and the command being run. It's not strictly required if there are no flag conflicts, but we recommend using it consistently to avoid ambiguity.
</Note>

Anything which is a process, can be run inside a nono sandbox - CLI tools, scripts, even interactive shells. The sandbox is applied to the entire process tree, so any child processes will also be restricted by the same permissions.

## Pre-Built Profiles

To get you going quickly, we provide pre-built profiles for popular AI agents and tools. These profiles bundle the right permissions for each tool, so you can get up and running with a single command.

Just search for your favorite coding agent from the registry

```bash theme={null}
nono search opencode
always-further/opencode	-	Official Always Further Opencode Plugin
```

And then run..

```bash theme={null}
nono run --profile always-further/claude -- claude
nono run --profile always-further/codex -- codex
nono run --profile always-further/pi -- pi
```

## Network Access

Network is **allowed by default**. Use `--block-net` to disable outbound connections:

```bash theme={null}
nono run --allow . --block-net -- cargo build
```

For granular control, use `--network-profile` for host-level filtering or `--open-port` for localhost IPC between sandboxes:

```bash theme={null}
# Host-level filtering via proxy
nono run --allow . --network-profile claude-code -- my-agent

# Allow specific domains through the proxy
nono run --allow . --allow-domain api.openai.com -- my-agent

# Localhost IPC (e.g., MCP server on port 3000)
nono run --block-net --open-port 3000 --allow . -- my-agent
```

See [Networking](/cli/features/networking) and [CLI Reference](/cli/usage/flags) for details.

## Interactive Shell (`nono shell`)

Start a shell with the same sandbox permissions as `nono run`:

```bash theme={null}
# Shell with access only to current directory
nono shell --allow .

# Shell with a named profile
nono shell --profile claude-code

# Override the shell binary
nono shell --allow-cwd --shell /bin/zsh
```

Exit the shell with `Ctrl-D` or `exit`.

## Checking Policy Access (`nono why`)

The `why` command checks if a filesystem path, network operation, kernel scope, or Tool Sandbox  command invocation would be allowed or denied. It's designed for both human debugging and programmatic use by AI agents.

```bash theme={null}
# Check if a sensitive path would be blocked
nono why --path ~/.ssh/id_rsa --op read
# Output: DENIED - sensitive_path (SSH keys and config)

# Check with capability context
nono why --path ./src --op write --allow .
# Output: ALLOWED - Granted by: --allow .

# JSON output for AI agents
nono why --json --path ~/.aws --op read
# {"status":"denied","reason":"sensitive_path","category":"AWS credentials",...}

# Check an Tool Sandbox  command/argv policy denial
nono why --profile gh --command gh -- issue comment 1052
# Output: DENIED - agents may read issues but not comment on them

# From inside a sandbox, query own capabilities
nono run --allow-cwd -- nono why --self --path /tmp --op write --json
```

| Flag        | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `--command` | Tool-sandbox command name to check                           |
| `--caller`  | Command-policy caller edge (default: `session`)              |
| `--path`    | Filesystem path to check                                     |
| `--op`      | Operation: `read`, `write`, or `readwrite` (default: `read`) |
| `--host`    | Network host to check (instead of `--path`)                  |
| `--port`    | Network port (default: 443)                                  |
| `--json`    | Output JSON for programmatic use                             |
| `--self`    | Query current sandbox state (inside sandbox)                 |

This is particularly useful for AI agents - when an operation fails, the agent can call `nono why --self` to get a structured JSON response explaining why and how to fix it.

## What Happens at Runtime

1. **Parse** — nono parses your capability flags
2. **Canonicalize** — All paths are resolved to absolute paths (prevents symlink escapes)
3. **Apply Sandbox** — Kernel sandbox is initialized (irreversible)
4. **Fork & Execute** — nono forks a sandboxed child process and runs your command inside it. The unsandboxed parent stays alive for audit recording, rollback, and diagnostics.
5. **Enforce** — Kernel blocks any unauthorized access attempts

## Sensitive Paths

The following paths are always blocked by default to protect credentials:

* `~/.ssh` - SSH keys
* `~/.aws`, `~/.gcloud`, `~/.azure` - Cloud credentials
* `~/.gnupg` - GPG keys
* `~/.kube`, `~/.docker` - Container credentials
* `~/.zshrc`, `~/.bashrc`, `~/.profile` - Shell configs (often contain secrets)
* `~/.npmrc`, `~/.git-credentials` - Package manager tokens

Use `nono why --path <path> --op read` to check if a specific path is blocked and why. See [Profiles & Groups](/cli/features/profiles-groups) for the full list and how group policy controls these.

## Agent Integration

For setting up nono with a specific AI agent:

* [Claude Code](/cli/clients/claude-code)
* [Codex](/cli/clients/codex)
* [OpenCode](/cli/clients/opencode)
* [OpenClaw](/cli/clients/openclaw)

<Note>
  If the agent you want to use cannot be found, create an [issue](https://github.com/always-further/nono/issues) to request consideration for adding it to the registry, or fork an existing profile and submit a PR with the new agent profile. See [Package Publishing](/cli/features/package-publishing) for details on publishing profiles.
</Note>

### Build your own profile

It's likely that you are going to want to customize the pre-built profiles or create your own for different tools and needs. You can do this easily with `nono profile init` which will create a new profile based on an existing one, with the option to customize it interactively.

```bash theme={null}
nono profile init claude --extends always-further/claude --full

nono profile Created profile at /Users/jdoe/.config/nono/profiles/claude.json
nono profile Validate with: nono profile validate claude
nono profile For editor autocomplete: nono profile schema -o nono-profile.schema.json
```

You can now call your own profile with `--profile claude` just like the pre-built ones.

From here, move to [Profiles & Groups](/cli/features/profiles-groups) for more indepth details on how to create and manage profiles, groups, and the policy engine.

## Next Steps

* [CLI Reference](/cli/usage/flags) - Complete flag documentation
* [Examples](/cli/usage/examples) - Common usage patterns