Nono

https://nono.sh/docs
Admin
Nono is a secure, kernel-enforced sandbox CLI and SDKs for AI agents and LLM workloads with...
Tokens:136,891
Snippets:1,801
Trust Score:6.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Generate Profiles

Source: https://nono.sh/docs/cli/usage/flags

Use the `--profiles` flag to generate example user profiles in `~/.config/nono/profiles/`.

```bash
nono setup --profiles
```

--------------------------------

### Zero Configuration Setup with nono

Source: https://nono.sh/docs/cli/internals/containers

Shows the simple installation and execution of nono for immediate use, contrasting with Docker's setup requirements.

```bash
brew install nono
nono run --allow-cwd -- my-agent
```

--------------------------------

### Nono Setup Command Syntax

Source: https://nono.sh/docs/cli/usage/flags

The `nono setup` command verifies the installation, tests sandbox support, and can optionally generate example profiles.

```bash
nono setup [OPTIONS]

```

--------------------------------

### Get Profile Authoring Guide

Source: https://nono.sh/docs/cli/features/profile-authoring

Run this command to display a comprehensive reference for LLM agents assisting with profile creation. Pipe or paste the output into your conversation for context.

```bash
nono profile guide
```

--------------------------------

### List and run examples

Source: https://nono.sh/docs/typescript/quickstart

Use these npm scripts to list available examples or run all of them.

```bash
npm run examples:list
npm run example:all
```

--------------------------------

### Start Proxy with Configuration

Source: https://nono.sh/docs/python/api/proxy-config

Example of starting the nono proxy with a custom ProxyConfig. This configures allowed hosts and routes for credential injection.

```python
from nono_py import ProxyConfig, RouteConfig, InjectMode, start_proxy

config = ProxyConfig(
    allowed_hosts=["api.openai.com", "*.anthropic.com"],
    routes=[
        RouteConfig(
            prefix="/openai",
            upstream="https://api.openai.com",
            credential_key="openai-key",
        ),
    ],
)
proxy = start_proxy(config)
```

--------------------------------

### Start Nono Proxy with Configuration

Source: https://nono.sh/docs/python/api/functions

Configure and start the Nono proxy with specified allowed hosts and routes. This example demonstrates setting up a proxy to route requests to OpenAI's API.

```python
from nono_py import ProxyConfig, RouteConfig, start_proxy, sandboxed_exec

config = ProxyConfig(
    allowed_hosts=["api.openai.com"],
    routes=[
        RouteConfig(
            prefix="/openai",
            upstream="https://api.openai.com",
            credential_key="openai-key",
        ),
    ],
)
proxy = start_proxy(config)

# Inject env vars into sandboxed child
env = list(proxy.env_vars().items()) + list(proxy.credential_env_vars().items())
result = sandboxed_exec(caps, ["python", "agent.py"], env=env)

# Collect audit trail and shut down
events = proxy.drain_audit_events()
proxy.shutdown()
```

--------------------------------

### Build and List Examples

Source: https://nono.sh/docs/typescript/examples

Commands to build the project in debug mode and list or run all available examples.

```bash
npm run build:debug
npm run examples:list
npm run example:all
```

--------------------------------

### Run Single Example

Source: https://nono.sh/docs/typescript/examples

Commands to execute a specific JavaScript or TypeScript example scenario.

```bash
npm run example:js:03-query-policy
npm run example:ts:03-query-policy
```

--------------------------------

### Quick Start: Storing and Running with Proxy Injection

Source: https://nono.sh/docs/cli/features/credential-injection

Demonstrates the steps to store credentials in the macOS system keystore and then run an agent with proxy-based credential injection enabled. This setup redirects API calls through the proxy.

```bash
# 1. Store credentials in the system keystore
security add-generic-password -s "nono" -a "openai_api_key" -w "sk-..."  # macOS

# 2. Run with credential injection
nono run --allow-cwd --network-profile claude-code --credential openai -- my-agent
```

--------------------------------

### Simplify Sandboxing with Nono

Source: https://nono.sh/docs/cli/internals/containers

Demonstrates replacing Docker for sandboxing with Nono. The 'Before' example uses Docker to run a Python script, while the 'After' example achieves the same with Nono, utilizing the host's Python installation.

```bash
# Before: Docker for sandboxing only
docker run -v $(pwd):/work -w /work python:3.11 python script.py

# After: nono (uses your installed Python, zero overhead)
nono run --allow-cwd -- python script.py
```

--------------------------------

### Install nono with Nix

Source: https://nono.sh/docs/cli/getting_started/installation

Install nono using Nix package manager. This example shows how to add it to your NixOS system configuration or load it into your current shell.

```nix
# Installing in NixOS
environment.systemPackages = [
  pkgs.nono
];
```

```bash
# Loading in shell
nix shell nixpkgs#nono
# Or using the legacy CLI
nix-shell -p nono
```

--------------------------------

### Initialize Project Files During Pack Installation

Source: https://nono.sh/docs/cli/features/managing-packs

Use `--init` to copy project-level instructions (e.g., a context file) into the current directory during pack installation. Without `--init`, these instructions are installed into the pack store but not copied.

```bash
nono pull always-further/claude --init
```

--------------------------------

### Full Capability Manifest Example

Source: https://nono.sh/docs/cli/internals/capability-manifest

A comprehensive example demonstrating filesystem grants and denials, network access rules, credential injection, process controls, and rollback settings.

```json
{
  "version": "0.1.0",
  "filesystem": {
    "grants": [
      { "path": "/workspace", "access": "readwrite" },
      { "path": "/usr/lib", "access": "read" }
    ],
    "deny": [
      { "path": "~/.ssh" },
      { "path": "~/.aws" }
    ]
  },
  "network": {
    "mode": "proxy",
    "allow_domains": [".googleapis.com"],
    "endpoints": [
      {
        "host": "api.github.com:443",
        "rules": [
          { "method": "GET", "path": "/repos/*/issues/**" },
          { "method": "POST", "path": "/repos/*/issues/*/comments" }
        ]
      }
    ],
    "ports": { "localhost": [5432] },
    "dns": true
  },
  "credentials": [
    {
      "name": "github",
      "upstream": "https://api.github.com",
      "source": "file:///vault/secrets/github-token",
      "inject": {
        "mode": "header",
        "header": "Authorization",
        "format": "Bearer {}"
      },
      "endpoint_rules": [
        { "method": "GET", "path": "/repos/*/issues/**" },
        { "method": "POST", "path": "/repos/*/issues/*/comments" }
      ]
    }
  ],
  "process": {
    "allowed_commands": ["git", "npm", "node"],
    "blocked_commands": ["rm", "sudo"],
    "signal_mode": "allow_same_sandbox",
    "ipc_mode": "full",
    "exec_strategy": "supervised"
  },
  "rollback": {
    "enabled": true,
    "exclude_patterns": ["node_modules"],
    "exclude_globs": ["*.log"]
  }
}
```

--------------------------------

### Example: Run OpenCode Agent

Source: https://nono.sh/docs/cli/clients/quickstart

An example of running the OpenCode agent using its specific profile.

```bash
# OpenCode
nono run --profile opencode -- opencode
```

--------------------------------

### Install a Pack

Source: https://nono.sh/docs/cli/features/managing-packs

Use `nono pull` to install a pack from the registry. On install, the CLI fetches the manifest, downloads artifacts and signatures, verifies bundles, checks signer identity, pins the identity, and installs artifacts.

```bash
nono pull always-further/claude
```

--------------------------------

### Configuration-Driven Sandbox

Source: https://nono.sh/docs/python/examples

Load and apply sandbox configurations from a JSON file. This allows for flexible and dynamic sandbox setup, specifying allowed paths with their access modes and network access settings. The example shows how to parse the config and apply the capabilities.

```python
from nono_py import CapabilitySet, AccessMode, SandboxState, apply
import json

def load_sandbox_from_config(config_path: str):
    """Load and apply sandbox from JSON config."""

    # Config format:
    # {
    #   "paths": [
    #     {"path": "/tmp", "access": "read_write"},
    #     {"path": "/data", "access": "read"}
    #   ],
    #   "network": false
    # }

    with open(config_path, "r") as f:
        config = json.load(f)

    caps = CapabilitySet()

    access_map = {
        "read": AccessMode.READ,
        "write": AccessMode.WRITE,
        "read_write": AccessMode.READ_WRITE,
    }

    for entry in config.get("paths", []):
        mode = access_map[entry["access"]]
        caps.allow_path(entry["path"], mode)

    if not config.get("network", True):
        caps.block_network()

    apply(caps)

load_sandbox_from_config("sandbox.json")
```

--------------------------------

### Setup Verbose Mode

Source: https://nono.sh/docs/cli/usage/flags

Use the `--verbose` or `-v` flag to show detailed information during setup. This flag can be specified multiple times for increased verbosity.

```bash
nono setup -v --profiles
```

--------------------------------

### Example: Listing Capabilities

Source: https://nono.sh/docs/python/api/fs-capability

Demonstrates how to list and inspect filesystem capabilities granted by a CapabilitySet.

```APIDOC
## Example: Listing Capabilities

This example shows how to create a `CapabilitySet`, add various path and file permissions, and then iterate through the resulting `FsCapability` objects to display their details.

```python
from nono_py import CapabilitySet, AccessMode

caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.allow_path("/data", AccessMode.READ)
caps.allow_file("/etc/hosts", AccessMode.READ)
caps.allow_file("/var/log/app.log", AccessMode.WRITE)

print("Filesystem Capabilities:")
print("-" * 60)

for cap in caps.fs_capabilities():
    kind = "file" if cap.is_file else "dir "
    print(f"  [{kind}] {cap.resolved}")
    print(f"         access: {cap.access}")
    print(f"         source: {cap.source}")
    print()
```

**Output:**

```
Filesystem Capabilities:
------------------------------------------------------------
  [dir ] /private/tmp
         access: AccessMode.READ_WRITE
         source: CapabilitySource(user)

  [dir ] /data
         access: AccessMode.READ
         source: CapabilitySource(user)

  [file] /private/etc/hosts
         access: AccessMode.READ
         source: CapabilitySource(user)

  [file] /private/var/log/app.log
         access: AccessMode.WRITE
         source: CapabilitySource(user)
```
```

--------------------------------

### Integrating nono within a Docker Container

Source: https://nono.sh/docs/cli/internals/containers

A Dockerfile example showing how to install and use nono inside a container, setting it to allow access to a '/work' directory.

```dockerfile
# Dockerfile
FROM ubuntu:22.04
COPY --from=ghcr.io/always-further/nono:latest /usr/bin/nono /usr/bin/nono
RUN apt-get update && \
    apt-get install -y --no-install-recommends libdbus-1-3 ca-certificates && \
    rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["nono", "run", "--allow", "/work"]
```

--------------------------------

### Comprehensive Platform Check Example

Source: https://nono.sh/docs/python/api/support-info

This example demonstrates a complete check of platform support, printing detailed information and providing specific guidance for unsupported Linux or macOS environments. It utilizes both `support_info` and `is_supported` from `nono_py`.

```python
from nono_py import support_info, is_supported

def check_platform():
    info = support_info()

    print(f"Platform: {info.platform}")
    print(f"Supported: {info.is_supported}")
    print(f"Details: {info.details}")

    if not info.is_supported:
        if info.platform == "linux":
            print("\nLinux detected but Landlock not available.")
            print("Ensure your kernel is 5.13+ and Landlock is enabled.")
        elif info.platform == "unsupported":
            print("\nThis platform is not supported.")
            print("nono requires Linux or macOS.")

    return info.is_supported

if not check_platform():
    exit(1)
```

--------------------------------

### Headless Quick Start with File-Backed Keys

Source: https://nono.sh/docs/cli/features/trust

A complete workflow for headless systems using file-backed keys for key generation, policy initialization, signing, and verification.

```bash
KEYREF="file://$HOME/.config/nono/trust/default.pem"

nono trust keygen --keyref "$KEYREF"
nono trust init --include "SKILLS.md" --include "CLAUDE.md" --keyref "$KEYREF"
nono trust sign-policy --keyref "$KEYREF"
nono trust sign --all --keyref "$KEYREF"
nono trust verify --all
```

--------------------------------

### Install nono-py with different package managers

Source: https://nono.sh/docs/python/installation

Alternative installation commands for uv, poetry, and pipenv.

```bash
pip install nono-py
```

```bash
uv add nono-py
```

```bash
poetry add nono-py
```

```bash
pipenv install nono-py
```

--------------------------------

### Install and Initialize pass for Secrets

Source: https://nono.sh/docs/cli/features/credential-injection

Installs the pass utility, generates a GPG key, and initializes pass with your GPG key ID. Recommended for headless environments.

```bash
sudo apt install pass
gpg --gen-key
pass init "your-gpg-key-id"
```

--------------------------------

### Start Session Attached

Source: https://nono.sh/docs/cli/features/session-lifecycle

Starts a session and attaches it to your current terminal for immediate interaction.

```bash
nono run --profile claude-code --allow-cwd -- claude
```

--------------------------------

### Setup Application with Sandbox

Source: https://nono.sh/docs/typescript/functions

Demonstrates a typical application setup using nono-ts for sandboxing. It checks for sandbox support, builds a capability set defining access permissions, and applies the sandbox. Handles potential errors during sandbox application.

```typescript
import {
  CapabilitySet,
  AccessMode,
  apply,
  isSupported,
  supportInfo,
} from 'nono-ts';

function setupApplication() {
  // 1. Check support
  const info = supportInfo();
  if (!info.isSupported) {
    console.warn(`Sandbox unavailable: ${info.details}`);
    return;
  }

  // 2. Build capabilities
  const caps = new CapabilitySet();

  // Application data
  caps.allowPath('/var/app/data', AccessMode.ReadWrite);

  // Configuration (read-only)
  caps.allowFile('/etc/app/config.json', AccessMode.Read);

  // Runtime libraries
  caps.allowPath('/usr/lib', AccessMode.Read);
  caps.allowPath('/lib', AccessMode.Read);

  // Temp directory
  caps.allowPath('/tmp', AccessMode.ReadWrite);

  // Block network if not needed
  if (!process.env.NEEDS_NETWORK) {
    caps.blockNetwork();
  }

  // 3. Apply sandbox
  try {
    apply(caps);
    console.log(`Sandbox active (${info.platform})`);
  } catch (error) {
    console.error('Sandbox failed:', error.message);
    process.exit(1);
  }
}

setupApplication();

```

--------------------------------

### Install nono-py using pip

Source: https://nono.sh/docs/python/installation

Use this command for the simplest installation of the nono-py package.

```bash
pip install nono-py
```

--------------------------------

### Example: Run Codex Agent

Source: https://nono.sh/docs/cli/clients/quickstart

An example of running the Codex agent using its specific profile.

```bash
# Codex
nono run --profile codex -- codex
```

--------------------------------

### Example: Run OpenClaw Gateway Agent

Source: https://nono.sh/docs/cli/clients/quickstart

An example of running the OpenClaw agent in gateway mode using its specific profile.

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

--------------------------------

### Create Web Server Capabilities

Source: https://nono.sh/docs/typescript/capability-set

Example demonstrating how to configure a CapabilitySet for a web server, including static file access, uploads, and runtime necessities.

```typescript
import { CapabilitySet, AccessMode } from 'nono-ts';

function createWebServerCapabilities(
  staticDir: string,
  uploadDir: string
): CapabilitySet {
  const caps = new CapabilitySet();

  // Static files (read-only)
  caps.allowPath(staticDir, AccessMode.Read);

  // Upload directory (read-write)
  caps.allowPath(uploadDir, AccessMode.ReadWrite);

  // Node.js runtime
  caps.allowPath('/usr/lib', AccessMode.Read);
  caps.allowPath('/lib', AccessMode.Read);

  // SSL certificates
  caps.allowPath('/etc/ssl/certs', AccessMode.Read);

  // DNS resolution
  caps.allowFile('/etc/resolv.conf', AccessMode.Read);
  caps.allowFile('/etc/hosts', AccessMode.Read);

  // Temp directory for uploads
  caps.allowPath('/tmp', AccessMode.ReadWrite);

  return caps;
}

const caps = createWebServerCapabilities('/var/www/html', '/var/uploads');
console.log(caps.summary());
```

--------------------------------

### Start Proxy and Use Environment Variables

Source: https://nono.sh/docs/python/api/proxy-config

Starts a proxy with a given configuration, retrieves environment variables for sandboxed execution, and processes audit events. Ensure the 'config' object is defined before use.

```python
proxy = start_proxy(config)

# Pass to sandboxed child
env = list(proxy.env_vars().items()) + list(proxy.credential_env_vars().items())
result = sandboxed_exec(caps, ["python", "agent.py"], env=env)

# Review what happened
for event in proxy.drain_audit_events():
    print(f"[{event['decision']}] {event['mode']} -> {event['target']}")

proxy.shutdown()
```

--------------------------------

### Development installation with uv

Source: https://nono.sh/docs/python/installation

Installs nono-py in editable mode with development dependencies and runs tests using uv. Assumes Rust toolchain is installed.

```bash
git clone https://github.com/always-further/nono-py.git
cd nono-py

# Install dependencies and build
uv sync
uv run maturin develop

# Run tests
uv run pytest tests/ -v
```

--------------------------------

### Resource Limits with Docker

Source: https://nono.sh/docs/cli/internals/containers

Example of how to configure resource limits (memory and CPU) for a Docker container.

```bash
docker run --memory=2g --cpus=1 my-agent
```

--------------------------------

### Setting up a Python Environment in Docker

Source: https://nono.sh/docs/cli/internals/containers

A Dockerfile example demonstrating how to set up a specific Python environment with necessary libraries like numpy, pandas, and tensorflow.

```dockerfile
FROM python:3.11
RUN pip install numpy pandas tensorflow
```

--------------------------------

### Complete Sandboxed Python Application Example

Source: https://nono.sh/docs/python/quickstart

A full example demonstrating checking support, building capabilities, applying the sandbox, and running restricted code, including expected permission errors.

```python
#!/usr/bin/env python3
"""Example sandboxed application."""

from nono_py import (
    CapabilitySet,
    AccessMode,
    apply,
    is_supported,
    support_info,
)


def main():
    # Check platform support
    if not is_supported():
        info = support_info()
        print(f"Error: {info.details}")
        return 1

    # Build capabilities
    caps = CapabilitySet()
    caps.allow_path("/tmp", AccessMode.READ_WRITE)
    caps.block_network()

    # Show what we're granting
    print("Capabilities:")
    print(caps.summary())

    # Apply sandbox
    apply(caps)
    print("\nSandbox applied!\n")

    # Run sandboxed code
    test_file = "/tmp/nono_test.txt"

    # Write to allowed path
    with open(test_file, "w") as f:
        f.write("Hello from sandbox!")
    print(f"Wrote to {test_file}")

    # Read from allowed path
    with open(test_file, "r") as f:
        content = f.read()
    print(f"Read: {content}")

    # Try to access disallowed path
    try:
        with open("/etc/passwd", "r") as f:
            f.read()
    except PermissionError:
        print("Blocked access to /etc/passwd (expected)")

    return 0


if __name__ == "__main__":
    exit(main())
```

--------------------------------

### Documentation Generator Example

Source: https://nono.sh/docs/cli/usage/examples

Run a documentation generator that reads source code and generates documentation, allowing output to a specific directory.

```bash
nono run \
  --read ./src \
  --allow ./docs \
  -- doc-generator
```

--------------------------------

### Example: Run Claude Code Agent

Source: https://nono.sh/docs/cli/clients/quickstart

An example of running the Claude Code agent using its specific profile.

```bash
# Claude Code
nono run --profile claude-code -- claude
```

--------------------------------

### Example Usage of SupportInfo

Source: https://nono.sh/docs/python/api/support-info

Demonstrates how to retrieve and interpret platform support information.

```APIDOC
## Example: Platform Check

This example shows how to fetch and display support information, including checks for unsupported platforms and specific Linux conditions.

```python
from nono_py import support_info

def check_platform():
    info = support_info()

    print(f"Platform: {info.platform}")
    print(f"Supported: {info.is_supported}")
    print(f"Details: {info.details}")

    if not info.is_supported:
        if info.platform == "linux":
            print("\nLinux detected but Landlock not available.")
            print("Ensure your kernel is 5.13+ and Landlock is enabled.")
        elif info.platform == "unsupported":
            print("\nThis platform is not supported.")
            print("nono requires Linux or macOS.")

    return info.is_supported

if not check_platform():
    exit(1)
```
```

--------------------------------

### Predicate Examples for Conditional Logic

Source: https://nono.sh/docs/cli/features/package-publishing

These examples showcase various 'when' predicates for conditional logic in pack configurations. They include OS targeting, version comparisons, distro-specific rules, and negation.

```json
{ "path": "/etc/pki", "when": "linux:rhel-like" }
```

```json
{ "path": "/private/var/db/sudo", "when": "macos:>=15" }
```

```json
{ "path": "/some/path", "when": ["linux:fedora:>=43", "linux:rhel-like:>=9"] }
```

```json
{ "path": "/legacy/path", "when": "!linux:nixos" }
```

--------------------------------

### start_proxy(config: ProxyConfig)

Source: https://nono.sh/docs/python/api/functions

Initializes and starts a proxy server based on the provided ProxyConfig. This is the main entry point for setting up network interception.

```APIDOC
## start_proxy(config: ProxyConfig)

### Description
Starts a proxy server with the given configuration.

### Example
```python
from nono_py import ProxyConfig, RouteConfig, start_proxy

config = ProxyConfig(
    allowed_hosts=["api.openai.com"],
    routes=[
        RouteConfig(
            prefix="/openai",
            upstream="https://api.openai.com",
            credential_key="openai-key",
        ),
    ],
)
proxy = start_proxy(config)

# ... use proxy ...

proxy.shutdown()
```
```

--------------------------------

### Setup Shell Integration

Source: https://nono.sh/docs/cli/usage/flags

Use the `--shell-integration` flag to display shell integration instructions, such as aliases.

```bash
nono setup --shell-integration
```

--------------------------------

### List Installed Packs

Source: https://nono.sh/docs/cli/features/managing-packs

List all packs currently installed on your machine. Machine-readable output is available with the `--json` flag.

```bash
nono list --installed
```

```bash
nono list --installed --json
```

--------------------------------

### Install nono with Homebrew

Source: https://nono.sh/docs/cli/getting_started/installation

Use Homebrew to install the nono CLI on macOS and Linux systems.

```bash
brew install nono
```

--------------------------------

### Audit Logging Examples

Source: https://nono.sh/docs/cli/features/networking

These examples show the format of audit logs for proxy decisions. Enable verbose logging to see these decisions.

```text
ALLOW CONNECT api.openai.com:443
DENY  CONNECT 169.254.169.254:80 reason=denied_cidr
```

--------------------------------

### Verify nono-py installation

Source: https://nono.sh/docs/python/installation

Python code to check the installed version and platform support information.

```python
import nono_py

# Check version
print(f"nono-py version: {nono_py.__version__}")

# Check platform support
info = nono_py.support_info()
print(f"Platform: {info.platform}")
print(f"Supported: {info.is_supported}")
print(f"Details: {info.details}")
```

--------------------------------

### Install Rust toolchain

Source: https://nono.sh/docs/python/installation

Required for building the nono-py SDK from source. This command downloads and runs the official Rust installation script.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Add Profile Guide to Project Instructions

Source: https://nono.sh/docs/cli/features/profile-authoring

Add this line to your project's instruction file to make the nono profile guide automatically available to your coding agent.

```md
Should you need to work with nono profiles or policy, you can retrieve context using the `nono profile guide` command
```

--------------------------------

### Install nono-ts with npm, yarn, or pnpm

Source: https://nono.sh/docs/typescript/overview

Install the nono Node.js SDK using your preferred package manager.

```bash
npm install nono-ts
```

```bash
yarn add nono-ts
```

```bash
pnpm add nono-ts
```

--------------------------------

### Get CapabilitySet Summary

Source: https://nono.sh/docs/python/api/capability-set

Use the summary() method to get a human-readable string describing the current filesystem and network capabilities.

```python
caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.allow_file("/etc/hosts", AccessMode.READ)
caps.block_network()

print(caps.summary())
```

--------------------------------

### Clone and build nono-py from source

Source: https://nono.sh/docs/python/installation

Steps to clone the repository and install the package using pip or maturin.

```bash
git clone https://github.com/always-further/nono-py.git
cd nono-py

# Install with pip
pip install .

# Or use maturin directly
pip install maturin
maturin develop
```

--------------------------------

### Install npm Dependencies

Source: https://nono.sh/docs/cli/usage/examples

Run npm install within the nono sandbox. This requires network access, which is allowed by default.

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

--------------------------------

### Get Started Detached Session ID

Source: https://nono.sh/docs/cli/features/session-lifecycle

After starting a detached session, nono prints a session ID and instructions on how to attach to it.

```text
Started detached session a3f7c2.
Attach with: nono attach a3f7c2
```

--------------------------------

### Example Session List Output

Source: https://nono.sh/docs/cli/features/session-lifecycle

An example of the output from the `nono ps` command, showing session details like ID, name, status, attachment state, PID, uptime, profile, and command.

```text
SESSION    NAME         STATUS     ATTACH     PID      UPTIME     PROFILE        COMMAND
a3f7c2     calm-node    running    detached   4821     2m         claude-code    claude
b8e1d4     -            running    attached   5103     30s        -              python3 main.py
```

--------------------------------

### CI Build Environment Profile Pattern

Source: https://nono.sh/docs/cli/features/profile-authoring

Example profile configuration for a locked-down CI build environment.

```json
{
  "meta": {
    "name": "ci-build",
    "description": "Locked-down CI environment"
  },
  "groups": {
    "include": ["deny_credentials"]
  },
  "workdir": { "access": "readwrite" },
  "network": { "block": true }
}
```

--------------------------------

### Retrieve and Log Filesystem Capabilities (TypeScript)

Source: https://nono.sh/docs/typescript/types

Example demonstrating how to retrieve filesystem capabilities from a CapabilitySet and log their details. This requires importing CapabilitySet and AccessMode.

```typescript
import { CapabilitySet, AccessMode } from 'nono-ts';

const caps = new CapabilitySet();
caps.allowPath('/tmp', AccessMode.ReadWrite);
caps.allowFile('/etc/hosts', AccessMode.Read);

const capabilities = caps.fsCapabilities();

for (const cap of capabilities) {
  console.log(`Path: ${cap.original}`);
  console.log(`  Resolved: ${cap.resolved}`);
  console.log(`  Access: ${cap.access}`);
  console.log(`  Is File: ${cap.isFile}`);
  console.log(`  Source: ${cap.source}`);
}
```

--------------------------------

### Combine detached startup with session naming

Source: https://nono.sh/docs/cli/usage/flags

This example shows how to combine the --detached flag with a custom session name and specify a working directory for the command.

```bash
nono run --detached --name nightly-indexer --allow ./workspace -- indexer
```

--------------------------------

### Example Workflow for Discovering and Applying Paths

Source: https://nono.sh/docs/cli/usage/troubleshooting

Demonstrates a typical workflow: run a command to discover needed paths, review the output, and then add those paths to your `nono run` command.

```bash
# 1. Run the command to discover paths:
nono run --profile opencode -- opencode
```

```bash
# 2. Review the output to see which paths are needed:
#    Read paths needed:
#      /usr/share/locale-langpack
#      /home/user/.config/opencode
#
#    Write paths needed:
#      /home/user/.cache/opencode
```

```bash
# 3. Add the paths to your nono command or profile:
nono run --read /usr/share/locale-langpack --allow ~/.config/opencode -- opencode
```

--------------------------------

### Get Capability Summary

Source: https://nono.sh/docs/typescript/capability-set

Obtain a human-readable string summarizing all filesystem and network capabilities that have been configured.

```typescript
summary(): string
```

```typescript
caps.allowPath('/tmp', AccessMode.ReadWrite);
caps.allowPath('/usr', AccessMode.Read);
caps.blockNetwork();

console.log(caps.summary());
// Filesystem:
//   /private/tmp [read+write] (dir)
//   /usr [read] (dir)
// Network:
//   outbound: blocked
```

--------------------------------

### summary

Source: https://nono.sh/docs/typescript/capability-set

Get a human-readable summary of all filesystem and network capabilities.

```APIDOC
## summary

### Description
Get a human-readable summary of all capabilities.

### Method
```typescript
summary(): string
```

### Parameters
None

### Response
#### Success Response (string)
A multi-line string describing all filesystem and network capabilities.

### Request Example
```typescript
// Assuming 'caps' is an instance of CapabilitySet
console.log(caps.summary());
```

### Response Example
```text
Filesystem:
  /private/tmp [read+write] (dir)
  /usr [read] (dir)
Network:
  outbound: blocked
```
```

--------------------------------

### Extending claude-code Profile Example

Source: https://nono.sh/docs/cli/clients/claude-code

This JSON configuration shows a custom user profile that extends the `claude-code` profile. When such a profile is used, nono detects the missing base and triggers the install prompt if `claude-code` is not already installed.

```json
{
  "extends": "claude-code",
  "meta": { "name": "claude-with-docs", "version": "1.0.0" },
  "filesystem": { "read": ["$HOME/Documents"]
}
}
```

--------------------------------

### Quick Start OpenCode with nono

Source: https://nono.sh/docs/cli/clients/opencode

Run OpenCode using the default 'opencode' profile, which grants necessary read/write access to project files and configuration directories, along with network access.

```bash
nono run --profile opencode -- opencode
```

--------------------------------

### Create an empty CapabilitySet

Source: https://nono.sh/docs/python/api/capability-set

Instantiate CapabilitySet to start defining sandbox permissions. By default, no permissions are granted and network access is allowed.

```python
caps = CapabilitySet()
print(caps)  # CapabilitySet(fs=0, network=allowed)
```

--------------------------------

### Data Processing Pipeline Example

Source: https://nono.sh/docs/cli/usage/examples

Execute a data processing agent that reads input data, writes output data, and uses a configuration file.

```bash
nono run \
  --read ./input \
  --write ./output \
  --read-file ./config.yaml \
  -- data-processor
```

--------------------------------

### GitHub Actions Signing Workflow

Source: https://nono.sh/docs/cli/features/trust

Example GitHub Actions workflow to automatically sign specified files using Nono CLI. It checks out code, installs Nono, signs files with keyless signing, and commits the resulting bundles.

```yaml
name: Sign files
on:
  push:
    branches: [main]
    paths:
      - 'SKILLS.md'
      - 'CLAUDE.md'
      - 'AGENT*'

permissions:
  id-token: write
  contents: write

jobs:
  sign:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install nono
        run: cargo install nono-cli

      - name: Sign files
        run: |
          for f in SKILLS.md CLAUDE.md;
          do
            [ -f "$f" ] && nono trust sign "$f" --keyless
          done

      - name: Commit bundles
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add '*.bundle'
          git diff --staged --quiet || git commit -m "Update file signatures"
          git push

```

--------------------------------

### CLI: Direct Environment Variable Injection with 1Password

Source: https://nono.sh/docs/cli/features/credential-injection

Example of using the `--env-credential-map` flag with a 1Password `op://` URI to inject a secret directly into an environment variable for CLI execution. Requires the `op` CLI to be installed and authenticated.

```bash
nono run --env-credential-map "op://Development/OpenAI API Key/credential" OPENAI_API_KEY -- my-agent
```

--------------------------------

### Initialize Nono Trust

Source: https://nono.sh/docs/cli/features/trust

Initializes the Nono trust setup for specified files. Use this to begin managing trust policies and signatures for your project.

```bash
nono trust init --include "SKILLS.md" --include "CLAUDE.md" --include "src/config.py"
```

--------------------------------

### Development installation with pip

Source: https://nono.sh/docs/python/installation

Installs nono-py in editable mode with development dependencies and runs tests. Assumes Rust toolchain is installed.

```bash
git clone https://github.com/always-further/nono-py.git
cd nono-py

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dev dependencies and build
pip install maturin pytest mypy ruff
maturin develop

# Run tests
pytest tests/ -v
```

--------------------------------

### Instant nono Startup vs. Docker Overhead

Source: https://nono.sh/docs/cli/internals/containers

Illustrates the near-instantaneous startup of nono compared to the significant overhead of launching a Docker container for similar tasks.

```bash
# Instant startup - no container overhead
nono run --allow-cwd -- claude-code
```

```bash
# Compare to Docker
docker run -v $(pwd):/work -it my-agent  # 100-500ms+ overhead per invocation
```

--------------------------------

### Code Review Agent Example

Source: https://nono.sh/docs/cli/usage/examples

Run a code review agent that reads source code from specified directories and writes review comments to another directory.

```bash
nono run \
  --read ./src \
  --read ./tests \
  --write ./reviews \
  -- code-review-agent
```

--------------------------------

### start_proxy

Source: https://nono.sh/docs/python/api/functions

Starts the nono network filtering proxy, which provides domain filtering, credential injection, and audit logging for sandboxed child processes.

```APIDOC
## start_proxy

### Description
Start the nono network filtering proxy.

Creates a localhost proxy server that provides domain filtering, credential injection, and audit logging for sandboxed child processes. The proxy runs on a background thread and is shut down via the returned handle.

### Method Signature
```python
start_proxy(config: ProxyConfig) -> ProxyHandle
```

### Parameters
#### Path Parameters
- **config** (ProxyConfig) - Required - Proxy configuration including allowed hosts, credential routes, and bind settings.

### Returns:
* `ProxyHandle` with `env_vars()`, `credential_env_vars()`, `drain_audit_events()`, and `shutdown()`.

### Raises:
* `RuntimeError` - Proxy failed to start (port in use, etc.)
```

--------------------------------

### Check nono-py installation status

Source: https://nono.sh/docs/python/installation

Command to verify if the nono-py package is installed in the current environment.

```bash
pip list | grep nono
```

--------------------------------

### Path Canonicalization Example

Source: https://nono.sh/docs/cli/usage/flags

Demonstrates how relative paths are resolved to absolute paths, symlinks are followed, and parent directory references are processed to prevent symlink escape attacks.

```bash
# These are equivalent if ./project resolves to /home/user/project
nono run --allow ./project -- command
nono run --allow /home/user/project -- command
```

--------------------------------

### Install nono Python package

Source: https://nono.sh/docs/quickstart

Install the nono package for Python projects using pip.

```bash
pip install nono
```

--------------------------------

### Install nono TypeScript package

Source: https://nono.sh/docs/quickstart

Install the nono package for TypeScript projects using npm.

```bash
npm install @anthropic-ai/nono
```

--------------------------------

### Nono Trust Init Command Options

Source: https://nono.sh/docs/cli/features/trust

Demonstrates various ways to initialize a trust policy using different include patterns, signing keys, and policy locations.

```bash
nono trust init --include "*.md"                    # single pattern
nono trust init --include "*.md" --include "*.py"   # multiple patterns
nono trust init --include "SKILLS*" --key my-key    # with specific signing key
nono trust init --keyref file:///path/to/key.pem    # with file-backed key
nono trust init --user                              # user-level policy (~/.config/nono/)
nono trust init --force                             # overwrite existing policy
```

--------------------------------

### Learn with All Paths

Source: https://nono.sh/docs/cli/usage/flags

Shows all accessed paths, not just those that would be blocked by the sandbox.

```bash
nono learn --all -- my-app
```

--------------------------------

### Check Platform Support and Apply Sandbox

Source: https://nono.sh/docs/python/overview

Use `is_supported()` to check for runtime sandboxing availability. Build a `CapabilitySet` by allowing or blocking specific paths and network access, then apply it irreversibly using `apply()`. This example demonstrates read/write access to `/tmp`, read access to `/etc/hosts`, and blocks all network access.

```python
from nono_py import CapabilitySet, AccessMode, apply, is_supported

# Check platform support
if not is_supported():
    print("Sandboxing not supported on this platform")
    exit(1)

# Build capability set
caps = CapabilitySet()
caps.allow_path("/tmp", AccessMode.READ_WRITE)
caps.allow_file("/etc/hosts", AccessMode.READ)
caps.block_network()

# Apply sandbox (irreversible!)
apply(caps)

# Process is now sandboxed
# - Can read/write in /tmp
# - Can read /etc/hosts
# - Cannot access network
# - Cannot access any other files
```

--------------------------------

### Start Detached Session

Source: https://nono.sh/docs/cli/features/session-lifecycle

Start a session in detached mode for long-running tasks. Use --rollback to enable rollback capabilities. After starting, you can check status with `nono ps` and attach later with `nono attach <session-id>`.

```bash
nono run --detached --rollback --profile claude-code --allow-cwd -- claude
```

```bash
nono ps
```

```bash
nono attach <session-id>
```

--------------------------------

### Create a New Integration Test File

Source: https://nono.sh/docs/cli/development/testing

Illustrates how to create a new integration test file, including sourcing the test helper library, setting up a temporary directory, and defining a basic test case using `expect_success`.

```bash
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "$SCRIPT_DIR/../lib/test_helpers.sh"

echo ""
echo -e "${BLUE}=== My New Tests ===${NC}"

verify_nono_binary

TMPDIR=$(setup_test_dir)
trap 'cleanup_test_dir "$TMPDIR"' EXIT

# Your tests here
expect_success "my test" "$NONO_BIN" run --allow "$TMPDIR" -- echo "hello"

print_summary
```

--------------------------------

### Install nono on Debian/Ubuntu

Source: https://nono.sh/docs/cli/getting_started/installation

Download and install the nono .deb package on Debian-based systems. It automatically determines the version and architecture.

```bash
VERSION=$(curl -sI https://github.com/always-further/nono/releases/latest | grep -i location | grep -oP 'v\K[0-9.]+')
ARCH=$(dpkg --print-architecture)
wget https://github.com/always-further/nono/releases/download/v${VERSION}/nono-cli_${VERSION}_${ARCH}.deb
sudo dpkg -i nono-cli_${VERSION}_${ARCH}.deb
```

--------------------------------

### SnapshotManager Usage Example

Source: https://nono.sh/docs/python/api/snapshot-manager

Demonstrates creating a SnapshotManager, capturing a baseline, detecting incremental changes, and performing a rollback. Ensure to expand '~' for the session directory path.

```python
from nono_py import SnapshotManager, ExclusionConfig

mgr = SnapshotManager(
    session_dir="~/.nono/rollbacks/session-001",
    tracked_paths=["/workspace"],
    exclusion=ExclusionConfig(
        exclude_patterns=["node_modules", "__pycache__"],
        exclude_globs=["*.pyc"],
    ),
)

# Capture baseline
baseline = mgr.create_baseline()
print(f"Merkle root: {baseline.merkle_root.hex()}")

# ... agent modifies files ...

# Capture changes
manifest, changes = mgr.create_incremental()
for change in changes:
    print(f"{change.change_type}: {change.path}")

# Roll back
mgr.restore_to(snapshot_number=0)
```

--------------------------------

### Initialize User-Level Trust Policy

Source: https://nono.sh/docs/cli/features/trust

Create a new user-level trust policy file at `~/.config/nono/trust-policy.json`. This command initializes the file with empty includes and sets your signing key as a publisher.

```bash
nono trust init --user
```

--------------------------------

### Define Application Hooks

Source: https://nono.sh/docs/cli/features/profiles-groups

Configure hooks to automatically install scripts for specific applications based on events and matchers. Installation is idempotent.

```json
{
  "hooks": {
    "claude-code": {
      "event": "PostToolUseFailure",
      "matcher": "Read|Write|Edit|Bash",
      "script": "nono-hook.sh"
    }
  }
}
```

--------------------------------

### Install nono from AUR

Source: https://nono.sh/docs/cli/getting_started/installation

Install nono from the Arch User Repository using AUR helpers like yay or paru, or manually with makepkg. This package is community-maintained.

```bash
# Using yay
yay -S nono-ai-bin

# Using paru
paru -S nono-ai-bin

# Manual install with makepkg
git clone https://aur.archlinux.org/nono-ai-bin.git
cd nono-ai-bin
makepkg -si
```

--------------------------------

### Start Detached Session with Rollback

Source: https://nono.sh/docs/cli/features/session-lifecycle

Start a detached session with rollback enabled for safety. This allows the agent to run unattended while preserving a rollback point if needed.

```bash
nono run --detached --rollback --profile claude-code --allow-cwd -- claude
```

--------------------------------

### Run Demo Commands

Source: https://nono.sh/docs/typescript/demonstrator

These commands demonstrate various ways to run the sandboxed file transformer demo, from building native addons to performing dry runs, applying the sandbox, and testing security attacks.

```bash
npm run build:debug
```

```bash
npm run demo:dry-run
```

```bash
npm run demo
```

```bash
npm run demo:attack-test
```

```bash
NONO_DEMO_KEEP_TMP=1 npm run demo:dry-run
```

--------------------------------

### Print Help Information with --help

Source: https://nono.sh/docs/cli/usage/flags

Use the --help or -h flag to print help information for the command.

```bash
nono run --help
```

--------------------------------

### Use Profile

Source: https://nono.sh/docs/cli/features/profile-authoring

Execute a command using the specified profile.

```bash
nono run --profile my-agent -- my-command
```

--------------------------------

### Safe Apply Pattern Examples

Source: https://nono.sh/docs/typescript/examples

Run JavaScript and TypeScript examples for the safe apply pattern, which guards irreversible apply() operations. The sandbox is only applied when NONO_APPLY=1 is set.

```bash
NONO_APPLY=1 npm run example:js:05-safe-apply-pattern
NONO_APPLY=1 npm run example:ts:05-safe-apply-pattern
NONO_APPLY=1 npm run example:js:10-subprocess-inheritance
NONO_APPLY=1 npm run example:ts:10-subprocess-inheritance
```

--------------------------------

### Initialize Trust Policy

Source: https://nono.sh/docs/cli/usage/flags

Use `nono trust init` to create a `trust-policy.json` file. Options control recursive scanning, directory exclusion, and key management.

```bash
nono trust init                            # Scan root directory only
```

```bash
nono trust init -r                         # Scan recursively
```

```bash
nono trust init -r --exclude-dirs tmp logs # Exclude extra directories
```

```bash
nono trust init --key my-key --force       # Specific key, overwrite existing
```

```bash
nono trust init --keyref file:///path/to/key.pem  # File-backed key
```

--------------------------------

### Start Attached Session and Detach Later

Source: https://nono.sh/docs/cli/features/session-lifecycle

Start a session attached to your terminal. You can detach later using Ctrl-] d or by running `nono detach <session-id>` from another terminal.

```bash
nono run --rollback --profile claude-code --allow-cwd -- claude
```

```text
Ctrl-] d
```

```bash
nono detach <session-id>
```

--------------------------------

### Start Session Detached

Source: https://nono.sh/docs/cli/features/session-lifecycle

Starts a session without attaching a client, allowing it to run in the background under supervisor management. Use the provided session ID to attach later.

```bash
nono run --detached --profile claude-code --allow-cwd -- claude
```

--------------------------------

### Scaffold and Use a New User Profile

Source: https://nono.sh/docs/cli/features/profiles-groups

Initializes a new user profile, inheriting from the default profile and including the 'node_runtime' group. It also shows how to validate the generated profile and use it with a command.

```bash
# Scaffold a profile that inherits from default with the node_runtime group
nono profile init my-agent --extends default --groups node_runtime

# Validate the generated profile
nono profile validate ~/.config/nono/profiles/my-agent.json

# Use the profile
nono run --profile my-agent -- my-agent-command
```

--------------------------------

### Update All Installed Packs

Source: https://nono.sh/docs/cli/features/managing-packs

Update all installed packs to their latest versions. This checks the registry, verifies signatures, and replaces local artifacts. Signer identity changes trigger a confirmation prompt.

```bash
nono update
```

--------------------------------

### Generate a New Profile

Source: https://nono.sh/docs/cli/features/profile-authoring

Use `nono profile init` to create a new profile. Options include specifying inheritance, groups, description, generating a full skeleton, or outputting to a specific path. Use `--force` to overwrite existing files.

```bash
# Minimal skeleton
nono profile init my-agent

# With inheritance and groups
nono profile init my-agent --extends default --groups deny_credentials

# With a description
nono profile init my-agent --extends default --description "Profile for my agent"

# Full skeleton with all sections
nono profile init my-agent --full

# Output to a specific path instead of ~/.config/nono/profiles/
nono profile init my-agent --output ./my-agent.json
```

--------------------------------

### Scaffold a New Profile

Source: https://nono.sh/docs/cli/features/profile-authoring

Use this command to initialize a new profile, specifying its name, parent profile, included groups, and whether to generate a full configuration.

```bash
nono profile init my-agent --extends default --groups deny_credentials --full
```

--------------------------------

### Compare Nono and Docker Startup Time

Source: https://nono.sh/docs/cli/internals/containers

Measures the startup time for Nono and Docker commands. Nono is instant, while Docker's time varies based on whether the image is cached or needs to be pulled.

```bash
# nono: instant
time nono run --allow-cwd -- echo hello
# real    0m0.005s

# Docker (warm, image cached)
time docker run alpine echo hello
# real    0m0.350s

# Docker (cold, needs pull)
time docker run alpine echo hello
# real    0m2.500s
```

--------------------------------

### Linux Secret Service: Install Dependencies

Source: https://nono.sh/docs/cli/features/credential-injection

Install the necessary tools for managing secrets with the Secret Service API on Debian/Ubuntu, Fedora, or Arch Linux. This includes `libsecret-tools` and a keyring daemon like `gnome-keyring`.

```bash
sudo apt install libsecret-tools gnome-keyring    # Debian/Ubuntu
```

```bash
sudo dnf install libsecret gnome-keyring           # Fedora
```

```bash
sudo pacman -S libsecret gnome-keyring             # Arch Linux
```

--------------------------------

### Learn with Legacy Tracer

Source: https://nono.sh/docs/cli/usage/flags

On macOS, uses the legacy unsandboxed `fs_usage` + `nettop` tracer for learning.

```bash
nono learn --trace -- my-app
```
Tokens:
Raw