NanoClaw Security Model

Trust Model

Entity	Trust Level	Rationale
Main group	Trusted	Private self-chat, admin control
Non-main groups	Untrusted	Other users may be malicious
Jail agents	Sandboxed	Isolated execution environment
Channel messages	User input	Potential prompt injection

Security Boundaries

1. Jail Isolation (Primary Boundary)

Agents execute in FreeBSD jails, providing:

Process isolation - Jail processes cannot affect the host
Filesystem isolation - Only explicitly mounted directories are visible
Non-root execution - Runs as unprivileged node user (uid 1000)
Ephemeral execution - Fresh jail-backed worker per invocation

This is the primary security boundary. Rather than relying on application-level permission checks, the attack surface is limited by what's mounted.

2. Mount Security

External Allowlist - Mount permissions stored at ~/.config/clawdie-cp/mount-allowlist.json, which is:

Outside project root
Never mounted into jails
Cannot be modified by agents

Default Blocked Patterns:

.ssh, .gnupg, .aws, .azure, .gcloud, .kube, .docker,
credentials, .env, .netrc, .npmrc, id_rsa, id_ed25519,
private_key, .secret

Protections:

Symlink resolution before validation (prevents traversal attacks)
Jail path validation (rejects .. and absolute paths)
nonMainReadOnly option forces read-only for non-main groups

Read-Only Project Root:

The main group's project root is mounted read-only. Writable paths the agent needs (group folder, IPC, .agent/) are mounted separately. This prevents the agent from modifying host application code (src/, dist/, package.json, etc.) which would bypass the sandbox entirely on next restart.

3. Session Isolation

Each group has isolated Claude sessions at data/sessions/{group}/.agent/:

Groups cannot see other groups' conversation history
Session data includes full message history and file contents read
Prevents cross-group information disclosure

4. IPC Authorization

Messages and task operations are verified against group identity:

Operation	Main Group	Non-Main Group
Send message to own chat	✓	✓
Send message to other chats	✓	✗
Schedule task for self	✓	✓
Schedule task for others	✓	✗
View all tasks	✓	Own only
Manage other groups	✓	✗

5. Credential Handling

Mounted Credentials:

Claude auth tokens (filtered from .env, read-only)

NOT Mounted:

Channel credentials outside allowlisted provider vars - host only
Mount allowlist - external, never mounted
Any credentials matching blocked patterns

Credential Filtering: Only these environment variables are exposed to jails:

const allowedVars = ['OPENROUTER_API_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY'];

Note: Provider credentials are passed into the jail worker so the agent can authenticate when it runs. This means the agent can potentially discover those credentials via Bash or file operations. The long-term goal is to reduce credential exposure inside the execution environment.

Privilege Comparison

Capability	Main Group	Non-Main Group
Project root access	`/workspace/project` (ro)	None
Group folder	`/workspace/group` (rw)	`/workspace/group` (rw)
Global memory	Implicit via project	`/workspace/global` (ro)
Additional mounts	Configurable	Read-only unless allowed
Network access	Unrestricted	Unrestricted
MCP tools	All	All

Security Architecture Diagram

┌──────────────────────────────────────────────────────────────────┐
│                        UNTRUSTED ZONE                             │
│  Channel Messages (potentially malicious)                         │
└────────────────────────────────┬─────────────────────────────────┘
                                 │
                                 ▼ Trigger check, input escaping
┌──────────────────────────────────────────────────────────────────┐
│                     HOST PROCESS (TRUSTED)                        │
│  • Message routing                                                │
│  • IPC authorization                                              │
│  • Mount validation (external allowlist)                          │
│  • Jail lifecycle                                                 │
│  • Credential filtering                                           │
└────────────────────────────────┬─────────────────────────────────┘
                                 │
                                 ▼ Explicit mounts only
┌──────────────────────────────────────────────────────────────────┐
│                   JAIL (ISOLATED/SANDBOXED)                       │
│  • Agent execution                                                │
│  • Bash commands (sandboxed)                                      │
│  • File operations (limited to mounts)                            │
│  • Network access (unrestricted)                                  │
│  • Cannot modify security config                                  │
└──────────────────────────────────────────────────────────────────┘

6.1 KiB Raw Blame History