> ## 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.

# Examples

> Common usage patterns and recipes for nono

## AI Coding Agents

### Claude Code

Run Claude Code with access limited to your project:

```bash theme={null}
nono run --allow . -- claude
```

Allow Claude to read your global config:

```bash theme={null}
nono run --allow . --read-file ~/.claude/config.json -- claude
```

Start an interactive shell inside the sandbox:

```bash theme={null}
nono shell --allow .
```

### OpenClaw

Run OpenClaw gateway with nono sandbox:

```bash theme={null}
nono run --profile openclaw -- openclaw gateway
```

Or manually specify permissions:

```bash theme={null}
nono run --allow ~/.openclaw -- openclaw gateway
```

### Generic AI Agent

```bash theme={null}
nono run --allow ./workspace -- my-ai-agent
```

## Checking Path Access

### Why is a path blocked?

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

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

### Check with capability context

```bash theme={null}
# Would ./src be writable if we use --allow .?
nono why --path ./src --op write --allow .
# Output: ALLOWED - Granted by: --allow .

# Check against a profile
nono why --path ./src --op read --profile claude-code
```

### Query from inside a sandbox

```bash theme={null}
# AI agents can query their own capabilities
nono run --allow-cwd -- nono why --self --path /tmp --op write --json
# {"status":"denied","reason":"not_in_allowed_paths",...}
```

### Check network access

```bash theme={null}
# Network is allowed by default
nono why --host api.openai.com --port 443
# Output: ALLOWED - network allowed by default

# Check with network blocked
nono why --host api.openai.com --block-net
# Output: DENIED - network_blocked
```

## Build Tools

### Cargo (Rust)

```bash theme={null}
# Full build with all access
nono run --allow . -- cargo build

# Read source, write only to target
nono run --read ./src --read ./Cargo.toml --read ./Cargo.lock --allow ./target -- cargo build
```

### npm/Node.js

```bash theme={null}
# Install dependencies (requires network, allowed by default)
nono run --allow . -- npm install

# Run build (offline)
nono run --allow . --block-net -- npm run build

# Run tests
nono run --allow . -- npm test
```

### Make

```bash theme={null}
nono run --allow . -- make
```

## Network Operations

### curl/wget

```bash theme={null}
# Download a file (network allowed by default)
nono run --write ./downloads -- curl -o ./downloads/file.tar.gz https://example.com/file.tar.gz

# API request
nono run --allow-cwd -- curl -X POST https://api.example.com/data
```

### Git Operations

```bash theme={null}
# Clone (network allowed by default)
nono run --allow ./repos -- git clone https://github.com/user/repo.git

# Local operations
nono run --allow . -- git status
nono run --allow . -- git commit -m "message"

# Push/pull (network allowed by default)
nono run --allow . -- git push
```

## Multi-Directory Access

### Separate Source and Output

```bash theme={null}
nono run --read ./src --allow ./dist -- webpack build
```

### Multiple Projects

```bash theme={null}
nono run --allow ./project-a --allow ./project-b -- my-tool
```

### Shared Dependencies

```bash theme={null}
nono run --allow . --read ~/.local/share/my-tool -- my-tool
```

## Debugging and Testing

### Dry Run

Preview what access would be granted:

```bash theme={null}
nono run --allow-cwd --read /etc --dry-run -- my-agent
```

### Verbose Output

```bash theme={null}
# Maximum verbosity
nono run -vvv --allow-cwd -- command
```

### Testing Sandbox Enforcement

```bash theme={null}
# Should succeed - writing to allowed path
nono run --allow . -- sh -c "echo test > ./allowed.txt"

# Should fail - writing outside allowed path
nono run --allow-cwd -- sh -c "echo test > /tmp/blocked.txt"

# Should succeed - network allowed by default
nono run --allow-cwd -- curl https://example.com

# Should fail - network blocked with --block-net
nono run --allow-cwd --block-net -- curl https://example.com
```

## Shell Scripts

### Running a Script

```bash theme={null}
nono run --allow . -- ./my-script.sh
```

### Inline Commands

```bash theme={null}
nono run --allow-cwd -- sh -c "echo hello && ls -la"
```

## Configuration Files

### Read-Only Config

```bash theme={null}
nono run --allow . --read-file ~/.config/myapp/config.toml -- myapp
```

### Multiple Config Files

```bash theme={null}
nono run --allow . \
  --read-file ~/.gitconfig \
  --read-file ~/.npmrc \
  -- my-tool
```

## Using Profiles

### Agent Profiles

```bash theme={null}
# Claude Code profile
nono run --profile claude-code -- claude

# OpenClaw profile
nono run --profile openclaw -- openclaw gateway
```

### Profile with Extra Permissions

```bash theme={null}
nono run --profile claude-code --read /tmp/extra -- claude
```

### Profile with Custom Workdir

```bash theme={null}
nono run --profile claude-code --workdir ./my-project -- claude
```

### Restrict Profile to Specific Domains

```bash theme={null}
nono run --profile claude-code --allow-domain api.openai.com -- claude
```

## Real-World Scenarios

### Code Review Agent

An agent that reads code and writes review comments:

```bash theme={null}
nono run \
  --read ./src \
  --read ./tests \
  --write ./reviews \
  -- code-review-agent
```

### Documentation Generator

An agent that reads source and generates docs:

```bash theme={null}
nono run \
  --read ./src \
  --allow ./docs \
  -- doc-generator
```

### Data Processing Pipeline

```bash theme={null}
nono run \
  --read ./input \
  --write ./output \
  --read-file ./config.yaml \
  -- data-processor
```

### Cloud Agent with Credential Access

By default, `~/.aws` and `~/.config/gcloud` are blocked by the `deny_credentials` group. Use `--bypass-protection` to grant targeted access:

```bash theme={null}
# AWS agent
nono run \
  --allow-cwd \
  --bypass-protection ~/.aws \
  --allow ~/.aws \
  -- my-aws-agent

# Multi-cloud agent
nono run \
  --allow-cwd \
  --bypass-protection ~/.aws \
  --bypass-protection ~/.config/gcloud \
  --allow ~/.aws \
  --read ~/.config/gcloud \
  -- multi-cloud-agent
```

### Offline Build Environment

```bash theme={null}
nono run \
  --allow-cwd \
  --block-net \
  -- make release
```

### IPC Between Sandboxed Processes

Run an MCP server and a client in separate sandboxes, communicating over localhost:

```bash theme={null}
# Terminal 1: MCP server on port 3000 (network blocked except IPC port)
nono run --block-net --open-port 3000 --allow ./mcp-server -- node server.js

# Terminal 2: Agent connects to the MCP server on port 3000
nono run --block-net --open-port 3000 --allow ./agent -- my-agent

# With proxy filtering + localhost IPC
nono run --network-profile claude-code --open-port 3000 --allow-cwd -- claude
```