# Shared Vault: Mounting a Directory into Multiple Agent Containers
*How to give multiple NanoClaw agents read/write access to the same folder on the host machine.*

---

## How it works

NanoClaw agents run in isolated Docker containers. By default, each agent can only see its own `/workspace/agent/` folder. The `additionalMounts` system lets you punch a controlled hole in that isolation — mapping a host directory into one or more containers so they all share the same files.

For a second brain / shared wiki, the target vault lives once on the host machine. Each agent that needs access gets it mounted. They all read and write the same files.

Mounted directories appear inside containers at:
```
/workspace/extra/<name>/
```

---

## Step 1 — Create the vault on the host machine

Pick a stable location for the vault. This path will be referenced in config files, so keep it permanent:

```bash
mkdir -p ~/second-brain
```

If you're using Obsidian, point it at this folder. If you're starting plain, it can stay empty for now.

---

## Step 2 — Add the directory to the mount allowlist (admin, one-time)

NanoClaw validates every mount request against an allowlist before the container starts. This is a security gate that only admins configure.

Create or edit `~/.config/nanoclaw/mount-allowlist.json` on the host:

```json
{
  "allowedRoots": [
    {
      "path": "~/second-brain",
      "allowReadWrite": true,
      "description": "Shared second brain / wiki vault"
    }
  ],
  "blockedPatterns": [
    ".ssh", ".gnupg", ".aws"
  ],
  "nonMainReadOnly": false
}
```

**Notes:**
- `allowReadWrite: true` is required for agents to write to the vault. Set to `false` if you want agents to be read-only.
- `nonMainReadOnly: false` means secondary/worker agents can also write. Set to `true` if you want only the primary agent to have write access.
- The `blockedPatterns` list is a safety net — always keep sensitive system directories there.
- This allowlist covers any subdirectory under `~/second-brain/`. You only set it up once regardless of how many agents you add.

---

## Step 3 — Add the mount to each agent's container.json

For each agent that should have vault access, edit its `container.json`. This file lives in the agent's workspace — from inside the container, that's `/workspace/agent/container.json`.

Add an entry to the `additionalMounts` array:

```json
{
  "mcpServers": {},
  "packages": {
    "apt": [],
    "npm": []
  },
  "additionalMounts": [
    {
      "hostPath": "/Users/james/second-brain",
      "containerPath": "second-brain",
      "readonly": false
    }
  ],
  "skills": "all"
}
```

**Fields:**
- `hostPath` — absolute path on the host machine (no `~` shorthand here — use the full path)
- `containerPath` — the name that appears inside the container under `/workspace/extra/`. Keep it short and consistent across all agents.
- `readonly` — `false` for read/write, `true` for read-only

**Access pattern inside the container:**
```
/workspace/extra/second-brain/
```

---

## Step 4 — Restart each agent container

Config changes don't take effect until the container restarts. From inside a container, an agent can request its own restart:

```bash
ncl groups restart
```

For a rebuild (if packages changed too):
```bash
ncl groups restart --rebuild
```

Both require admin approval. Once approved, the container restarts and the vault will be available at `/workspace/extra/second-brain/`.

---

## Step 5 — Verify the mount

After restart, from inside the container:

```bash
ls /workspace/extra/second-brain/
```

If the directory is empty (fresh vault), it will return nothing but no error. If it shows files, the mount is live.

---

## Repeating for additional agents

Steps 1 and 2 are done once. For each new agent:
1. Edit its `container.json` (Step 3)
2. Restart it (Step 4)

That's it — they all share the same vault on the host.

---

## What each agent sees

| Path in container | Path on host |
|---|---|
| `/workspace/extra/second-brain/` | `~/second-brain/` |
| `/workspace/extra/second-brain/wiki/` | `~/second-brain/wiki/` |
| `/workspace/extra/second-brain/raw/` | `~/second-brain/raw/` |

---

## Security notes

- Mounts bypass group isolation by design. Only mount directories you're comfortable with each agent reading (and writing, if `readonly: false`).
- If a mount fails validation (path not in allowlist, blocked pattern, wrong permissions), NanoClaw silently skips it — the container still starts, the mount just won't be there. Check the path and allowlist if something isn't showing up.
- Agent workspaces (`/workspace/agent/`) remain fully isolated per-agent even when a shared vault is mounted.