Troubleshooting - Nono Docs

Permission Denied Errors

Symptom

Command fails with “Permission denied” or “Operation not permitted” errors.

Diagnosis

Check what access was granted:

nono run --allow-cwd --dry-run -- command

Query capabilities from inside the sandbox:

# Check if a specific path is accessible
nono run --allow-cwd -- nono why --self --path /var --op write --json

# Human-readable output
nono run --allow-cwd -- nono why --self --path ~/.ssh --op read

Run with verbose logging:
nono run -vvv --allow-cwd -- command

Common Causes

Cause	Solution
Path not in allowed list	Add path with `--allow`, `--read`, or `--write`
Sensitive path blocked	Use `--bypass-protection` with your grant (see below)
Relative path resolved differently	Use absolute paths
Symlink target outside sandbox	Grant access to the symlink target
File replaced after sandbox start (Linux)	Grant the containing directory, or restart the sandbox (see below)

Sensitive Paths

These paths are blocked by default, even if a parent directory is allowed:

~/.ssh/ - SSH keys
~/.aws/ - AWS credentials
~/.gnupg/ - GPG keys
~/.kube/ - Kubernetes config
~/.docker/ - Docker credentials
Shell history files
Shell configuration files

Why? These paths commonly contain secrets that an AI agent should never access. If you grant one of these paths with --allow, nono will warn you on macOS:

WARN '~/.gnupg' is blocked by 'deny_credentials'; use --bypass-protection ~/.gnupg to allow access

To intentionally access a blocked path, use --bypass-protection alongside your grant:

nono run --allow ~/.gnupg --bypass-protection ~/.gnupg -- gpg --list-keys

Stale File Grants (Linux)

On Linux, a file-level grant (--read-file, --write-file, --allow-file, or profile read_file/write_file/allow_file) attaches to the file’s inode at sandbox start, not to its path. If the file is later replaced atomically — the write-temp-then-rename() pattern used by editors, git config, systemd-resolved, and most config tools — the path points to a new inode that carries no rule, and access fails with EACCES for the rest of the session even though the grant still names the path. nono why detects this from inside the sandbox and reports it:

DENIED
  Reason: stale_file_grant
  Details: The sandbox granted this file, but the file at ... was replaced
  after sandbox start (inode 39:175234 when the sandbox started, 39:175245
  now). ...

Remedies:

Restart the sandbox session — grants re-resolve to the current file.
If the file is rewritten routinely, grant its containing directory instead: directory rules cover files created after sandbox start, so they survive atomic replacement (at the cost of a broader grant).

Network Connection Failed

Symptom

Commands like curl, wget, or API calls fail with connection errors.

Possible Causes

Network explicitly blocked - You used --block-net flag
Actual network issue - DNS, firewall, or connectivity problem
Application-specific issue - App needs specific configuration

Solutions

If you used --block-net, remove it:

# Network is allowed by default
nono run --allow-cwd -- curl https://example.com

Check if network is allowed from inside the sandbox:

nono run --allow-cwd -- nono why --self --host example.com --json
# Should show {"status":"allowed",...}

Test network outside nono:

curl https://example.com
# If this fails, it's not a nono issue

Command Not Found

Symptom

nono: command not found

error: No such file or directory: my-command

Solutions

nono not in PATH:

# Add to PATH
export PATH="$PATH:/path/to/nono/target/release"

Target command not in PATH:

# Use absolute path
nono run --allow-cwd -- /usr/local/bin/my-command

# Or ensure PATH is set correctly
nono run --allow-cwd -- sh -c 'which my-command'

Sandbox Initialization Failed

Symptom

Error: Sandbox initialization failed: ...

Linux (Landlock)

Check kernel version:
uname -r # Must be 5.13+ for Landlock

Check Landlock is enabled:

cat /sys/kernel/security/lsm
# Should include "landlock"

Enable Landlock (if missing): Add lsm=landlock,... to kernel boot parameters

macOS (Seatbelt)

Check macOS version:

sw_vers
# Should be 10.15 (Catalina) or later

Check for SIP issues: Some system integrity protection settings can interfere. This is rare.

Dry Run Shows Different Paths

Symptom

Paths in dry-run output don’t match what you specified.

Explanation

nono canonicalizes all paths:

Relative paths become absolute
Symlinks are resolved
.. and . are normalized

This is intentional to prevent symlink escape attacks.

Example

$ pwd
/home/user/project

$ nono run --allow-cwd --dry-run -- command
Capabilities:
  [rw] /home/user/project    # Resolved from "."

Child Process Doesn’t Inherit Sandbox

Symptom

You expect a child process to be sandboxed but it seems to have more access.

This Shouldn’t Happen

Child processes always inherit sandbox restrictions. If you’re seeing this:

Verify the parent is sandboxed:

# The --self flag only works inside a sandbox
nono run --allow-cwd -- nono why --self --path /etc --op read
# Should show current sandbox capabilities

Check if you’re testing correctly:

# Parent and child are BOTH sandboxed
nono run --allow-cwd -- sh -c 'sh -c "cat /etc/passwd"'
# Should fail if /etc is not allowed

If you have a reproducible case where a child escapes the sandbox, please report it as a security issue.

Performance Issues

Symptom

Commands run slower under nono.

Explanation

There is minimal overhead from sandbox initialization (microseconds). If you’re seeing significant slowdowns:

First run may be slower due to path canonicalization
Many file operations may show overhead from kernel permission checks

Solutions

Grant access to larger directories instead of many individual files
Use --read for directories that don’t need write access (slightly faster path)

Using `nono why --self` for Debugging

When running inside a nono sandbox, you can query your own capabilities using nono why --self:

# Check if a path would be readable
nono run --allow-cwd -- nono why --self --path ~/.ssh --op read
# Output: DENIED - sensitive_path (SSH keys and config)

# Check if a path would be writable
nono run --allow . -- nono why --self --path ./src --op write
# Output: ALLOWED - Granted by: --allow .

# JSON output for programmatic use (useful for AI agents)
nono run --allow-cwd -- nono why --self --path /var --op write --json
# {"status":"denied","reason":"not_in_allowed_paths","suggestion":"--write /var"}

# Check network status
nono run --allow-cwd -- nono why --self --host api.openai.com
# Output: ALLOWED - network allowed by default

# Check network when blocked
nono run --allow-cwd --block-net -- nono why --self --host api.openai.com
# Output: DENIED - network_blocked

The --self flag reads the sandbox state from NONO_CAP_FILE, which is the only environment variable nono sets. This is designed for programmatic introspection by AI agents rather than debugging via shell variables.

Platform-Specific Issues

macOS: “killed: 9” or Immediate Termination

This usually means the Seatbelt profile was malformed. Run with -vvv to see the generated profile:

nono run -vvv --allow-cwd -- command

Linux: “Landlock not supported”

Your kernel may not have Landlock enabled. Check:

# Verify kernel version
uname -r

# Check LSM list
cat /sys/kernel/security/lsm

Linux: Network Restrictions Not Working

Network filtering requires Landlock ABI v4 (kernel 6.7+):

# Check kernel version
uname -r

# If < 6.7, network filtering is unavailable via Landlock

Discovering Required Paths

If you’re getting permission errors and aren’t sure which paths your application needs, run the command under nono run. nono reports denied paths at exit with suggested fix flags. When running with a profile it also prompts to save a patch:

# Run without a profile — denials and suggested flags reported at exit
nono run -- my-app

# Run with a profile — same, plus prompts to save a profile patch
nono run --profile my-profile -- my-app

Example Workflow

Run your command — nono will sandbox it and report any denials at exit:
nono run --profile nolabs-ai/opencode -- opencode

If paths were blocked, nono reports them at exit with suggested fix flags:

Sandbox denial: 2 paths blocked.
  /home/user/.config/opencode (read)
  /home/user/.cache/opencode (read+write)
Fix flags: --read ~/.config/opencode --allow ~/.cache/opencode

Re-run with the suggested flags, or accept the prompt to save them as a profile patch:
nono run --read ~/.config/opencode --allow ~/.cache/opencode -- opencode

WSL2-Specific Issues

Sandbox initialization: EBUSY on seccomp

Symptom: Sandbox initialization failed with EBUSY when using --capability-elevation. Cause: WSL2’s init process (PID 1) installs its own seccomp user notification filter. The Linux kernel only allows one notify listener per filter chain, so nono’s attempt to install a second returns EBUSY. Solution: nono automatically disables capability elevation on WSL2. If you see this error, ensure you’re running a recent version. This is tracked in microsoft/WSL#9548.

Credential proxy refused on WSL2

Symptom: WSL2: proxy-only network mode cannot be kernel-enforced Cause: The proxy’s network lockdown depends on seccomp notify or Landlock V4, neither of which is available on WSL2. Solutions:

Use --env-credential instead of --credential (env var injection works normally)
Opt in to degraded proxy mode with wsl2_proxy_policy: "insecure_proxy" in your profile’s security config (details)

Per-port network filtering unavailable

Symptom: --open-port or --listen-port fails on WSL2. Cause: Landlock V4 (kernel 6.7+) is required for TCP port filtering. WSL2 ships kernel 6.6. Solution: Use --block-net for full network isolation, or wait for a WSL2 kernel upgrade to 6.7+.

Verifying WSL2 compatibility

Run nono setup --check-only inside WSL2 to see the full feature availability matrix:

nono setup --check-only

This reports the detected kernel version, Landlock ABI, WSL2 detection status, and which features are available.

Running Inside Docker/Podman

Proxy notification bootstrap failures

On Linux kernels without Landlock V4 networking, the CLI transfers the proxy notification listener through a short CLONE_FILES bootstrap. This handoff does not use pidfd_getfd or require CAP_SYS_PTRACE. An error mentioning pidfd_getfd failed comes from the older handoff; update nono to use the new one. A CLONE_FILES bootstrap error means startup failed before the listener handoff completed. Check that the container’s syscall policy permits seccomp user notifications, clone with CLONE_FILES, and descriptor-table detachment through either close_range with CLOSE_RANGE_UNSHARE or unshare(CLONE_FILES). The supervisor also needs access to the child’s procfs entries for notification mediation. If these requirements cannot be met, nono aborts startup instead of running the command without its restrictions.

Getting Help

If you’re still stuck:

Search existing issues: GitHub Issues
Open a new issue with:
- nono version (nono --version)
- OS and kernel version
- Full command that failed
- Error message
- Output of nono run --dry-run with same flags

​Permission Denied Errors

​Symptom

​Diagnosis

​Common Causes

​Sensitive Paths

​Stale File Grants (Linux)

​Network Connection Failed

​Symptom

​Possible Causes

​Solutions

​Command Not Found

​Symptom

​Solutions

​Sandbox Initialization Failed

​Symptom

​Linux (Landlock)

​macOS (Seatbelt)

​Dry Run Shows Different Paths

​Symptom

​Explanation

​Example

​Child Process Doesn’t Inherit Sandbox

​Symptom

​This Shouldn’t Happen

​Performance Issues

​Symptom

​Explanation

​Solutions

​Using nono why --self for Debugging

​Platform-Specific Issues

​macOS: “killed: 9” or Immediate Termination

​Linux: “Landlock not supported”

​Linux: Network Restrictions Not Working

​Discovering Required Paths

​Example Workflow

​WSL2-Specific Issues

​Sandbox initialization: EBUSY on seccomp

​Credential proxy refused on WSL2

​Per-port network filtering unavailable

​Verifying WSL2 compatibility

​Running Inside Docker/Podman

​Proxy notification bootstrap failures

​Getting Help

Permission Denied Errors

Symptom

Diagnosis

Common Causes

Sensitive Paths

Stale File Grants (Linux)

Network Connection Failed

Symptom

Possible Causes

Solutions

Command Not Found

Symptom

Solutions

Sandbox Initialization Failed

Symptom

Linux (Landlock)

macOS (Seatbelt)

Dry Run Shows Different Paths

Symptom

Explanation

Example

Child Process Doesn’t Inherit Sandbox

Symptom

This Shouldn’t Happen

Performance Issues

Symptom

Explanation

Solutions

Using `nono why --self` for Debugging

Platform-Specific Issues

macOS: “killed: 9” or Immediate Termination

Linux: “Landlock not supported”

Linux: Network Restrictions Not Working

Discovering Required Paths

Example Workflow

WSL2-Specific Issues

Sandbox initialization: EBUSY on seccomp

Credential proxy refused on WSL2

Per-port network filtering unavailable

Verifying WSL2 compatibility

Running Inside Docker/Podman

Proxy notification bootstrap failures

Getting Help