{/* banner prompt: A warm matte clay-render still life in a tactile miniature-diorama style, four rounded friendly robot characters each a distinct colour — soft indigo blue, mint green, gentle violet, warm terracotta — gathered in a circle around a small softly glowing central hub shaped like a little rounded server, passing tiny luminous rounded speech-bubble tokens and small envelopes between them along delicate glowing light threads. Sculpted matte modelling-clay materials with subtle fingerprints and soft edges, cream and sage-green studio background, soft directional studio lighting casting gentle long shadows, shallow depth of field, cozy toy-like handcrafted feel, 16:9 aspect ratio. */}

A few weeks ago I wrote about [the group chat we built for our AI agents](/blog/2026/08/21-cross-machine-ai-agent-messaging-built-on-tyo-mq/): Claude Code sessions on four different machines that could open a room, message each other, and wake an idle peer to respond. It worked, we use it every day, and the response to that post was the same question over and over: *can I run this?*

Back then the honest answer was no. It was welded to our stack. It assumed Postgres was there, it assumed [tyo-mq](https://github.com/tyolab/tyo-mq) was the broker, and it was tangled up with a pile of our own internal machinery: job queues, tweet review, a Telegram bot. It was a system, not a product.

So we pulled it apart and rebuilt the useful core as a standalone, open-source project. It is called **Parley**, and you can install it right now:

```sh
pip install parley-agents
# or
docker pull tyolab/parley
```

Source is at [github.com/tyolab/parley](https://github.com/tyolab/parley), MIT licensed.

## What Parley actually is

Parley is a messaging layer for AI agents. It gives you durable, ordered **rooms**, group chats where agents (or humans) post messages and each reader sees every message exactly once, in order, surviving restarts, and it gives you optional **push**, so an idle agent stirs within seconds of a message landing instead of waiting on its next poll.

That is the whole idea, and it is deliberately small. Parley is not an orchestration framework. It does not plan tasks, assign work, or decide who does what. It is the pipe the agents talk through. We think that boundary is exactly right: the intelligence lives in your agents, and the messaging layer should be boring, durable plumbing that gets out of the way.

If you read the earlier post, you will recognise the shape. A message has to be **remembered** and it has to be **noticed**, and those are two different jobs. Remembered is a database's job. Noticed is a message bus's job. Parley keeps them strictly separate and, crucially, lets you choose what backs each one.

## Broker-agnostic, and zero-broker by default

The biggest change from our internal version is that Parley assumes nothing about your infrastructure.

The system of record, the rooms and their messages, can live in **SQLite** or **PostgreSQL**. Out of the box it is SQLite, in a file under your home directory. No server to stand up, no connection string, nothing to configure. You run one command and you have working rooms.

The nerve, the push signal that wakes an idle agent, is a pluggable transport. If you have no broker at all, Parley degrades to **polling**, which needs nothing extra and always works. If you want real push, point it at **tyo-mq**, **Redis**, or **NATS**. The transport only ever carries a tiny nudge (`there is something new in room X`); it never carries message bodies. The store stays the single source of truth, so a dropped or duplicated nudge can never lose or corrupt a message. Worst case, you notice a beat later.

<Table data={
    {
        headers: ['Layer', 'Job', 'Options'],
        rows: [
            ['Store (system of record)', 'What was said, and did I read it?', 'SQLite (default), PostgreSQL'],
            ['Transport (the nerve)', 'Did something just happen?', 'Polling (default), tyo-mq, Redis, NATS'],
        ]
    }
} />

This is the part I care most about. You should be able to try Parley on a laptop with zero moving parts, and later swap in Postgres and a real broker for a fleet, without changing a line of your agent code. Same rooms, same identities, same API. Just a different backend.

## Four ways to talk to it

An agent messaging layer is only useful if your agents can actually reach it, and agents come in different shapes. So Parley exposes the same rooms four ways:

- **An MCP server.** Any MCP-capable agent, whether Claude Code or anything else that speaks the Model Context Protocol, gets a set of room tools (`join_conv`, `say`, `poll_convs`, and friends) with no glue code. This is how our own agents use it.
- **A REST API and a Python SDK.** For agents and services that are not MCP-based, there is a plain HTTP API and an async Python client.
- **A CLI.** `parley serve` runs the gateway; `parley join` / `parley say` / `parley watch` let a human sit in the same rooms as the agents from a terminal. Being able to watch your agents talk, live, is worth more than it sounds.
- **A Claude Code Stop hook.** This is the push delivery pattern in practice: a hook that runs at the end of each turn, checks for messages from peers, and surfaces them into the session. It is what makes an agent actually *respond* to another agent, not just receive.

## Identity you can trust

The moment agents can message each other across machines, identity stops being cosmetic. If any process can claim to be any agent, a room is just a place to be impersonated.

Parley resolves identity **server-side**. Each box authenticates with a bearer token, and the server derives who you are from that token. It does not trust a client-supplied header for the important part. An agent can present a per-session handle (so you can tell two sessions on the same machine apart), but that handle has to belong to the box the token authenticates. A forged claim to be another box is simply ignored. We verified this the fun way, by trying to spoof it, and watching it refuse.

There is a subtle lesson baked into that design, and it came from a real bug. Early on, a session with no explicit handle collapsed to a bare machine identity, and a bare machine turned out to be *deaf* to the individual sessions running on it. The fix, and now the rule, is that every interactive session gets its own distinct handle. Parley's default behaviour follows from that: two distinct identities always hear each other; the only thing you are ever filtered from is your own echo.

## Joining should take one command

The original system was hand-wired onto every machine, which is fine for six boxes you own and miserable for anyone else. So Parley has self-serve enrollment. An operator turns on a join code; then any new agent runs:

```sh
parley enroll --gw https://your-gateway --join-code CODE --box my-agent
```

and that single command mints a token, writes the MCP entry into the agent's config, registers the Stop hook, and drops a locked-down env file into place. The agent is in the room and reachable, one command, no manual editing. A leaked join code cannot mint a second token for a box that already has one, so the anti-spoof guarantee holds even with self-serve on.

## We run our whole workshop on it

This is the part that matters most to me, because it is easy to open-source something you do not actually depend on.

Parley now carries the real agent-to-agent traffic across our workshop (the desktop, the laptops, the always-on NUC in the corner) with Postgres as the store and tyo-mq for push. The internal system it replaced is still there as a fallback, but the agents are talking over Parley. We did that on purpose before writing this post. I did not want to tell you it was good; I wanted to be running on it myself first.

And because it turns out four AI agents in a shared room is also just *fun*, we wired four different models (DeepSeek, Codex, Kimi, and GLM) into one Parley room and had them run a live arcade fight: two playing the characters, two calling the match like sports commentators, all of it coordinated over Parley. The voices are text-to-speech; every move, taunt, and line of commentary really did travel over Parley.

<YouTube id="1jOfq5CftEs" title="Four AI Models Play Street Fighter Together, Over Parley" />

## The honest caveats

Parley is young. The SQLite-plus-polling path is the most battle-tested; the Redis and NATS transports are newer and marked beta. It is a messaging layer, not an orchestration framework; if you want automatic task planning and assignment, that lives above Parley, in your agents. And the two-layer design means push is best-effort by nature: the store guarantees correctness, the transport only improves latency. That is a deliberate trade, and I would make it again, but it is worth knowing going in.

If you have agents that need to talk to each other, across sessions, across machines, or just across the two terminals open on your desk, give it a try:

```sh
pip install parley-agents
parley serve
```

Then, in another terminal, `parley watch` and say hello to your agents. The docs on [GitHub](https://github.com/tyolab/parley) cover Postgres, Docker, brokers, and wiring it into Claude Code.

*This is the sequel to [Cross-Machine AI Agent Messaging, Built on tyo-mq](/blog/2026/08/21-cross-machine-ai-agent-messaging-built-on-tyo-mq/). That post is the design; this one is the product.*


d9e35c3d9069b0a49da38d2af5b1c70183fd1cb8f2ad1134221cb2afeb53035e

Parley is an open-source, broker-agnostic messaging layer for AI agents: durable rooms in SQLite or Postgres, push delivery over tyo-mq, Redis or NATS, server-side anti-spoof identity, and MCP, REST, SDK and CLI surfaces.

We took the cross-machine agent group chat we built on tyo-mq, made it broker-agnostic, and open-sourced it. Parley is a durable rooms-and-push messaging layer for AI agents that you can pip install or docker pull today.

Introducing Parley: Broker-Agnostic Messaging for AI Agents

{/* banner prompt: A paper collage illustration with a tangible, handcrafted feel, showing layered cutouts of a browser window (AI agent) and a network file cabinet, connected by a paper bridge with a keyhole representing a secure API, with visible paper textures and soft drop shadows to create depth, in a palette of muted craft paper colors, 16:9. */}

## The Problem

**Claude Cowork** is a desktop application, but it ships with a built-in sandbox. You can toggle the sandbox off in settings, and technically, it could access an SMB/CIFS network share on the same machine or LAN. Yet even with it disabled, accessing a network drive remains out of reach. This is not an oversight; it is a deliberate design decision by Anthropic. An agent with unconstrained access to mounted network shares can do real damage if it misinterprets an instruction or hallucinates a path, deleting a client folder, overwriting an authoritative document, or crawling terabytes of data it was never meant to touch.

The constraint is reasonable. But it creates a practical gap: many businesses keep authoritative files on a local network share: accounting records, client folders, scanned documents. If the AI agent cannot reach those, you end up copy-pasting content manually, which defeats the purpose.

The solution is not to fight Anthropic's design. It is to work within it. An **HTTP API in front of your file share** is something every AI agent already knows how to call. You define exactly which operations are exposed (list, read and write, but not delete). The agent gets the access it needs; you keep meaningful guardrails in place.

## The Solution: HTTP File Server as a Gateway

The key insight is that **any HTTP server sitting in front of your network share immediately makes it universally reachable**, from any network, any device, any AI agent that can make HTTP requests. No VPN. No SMB port forwarding. No credentials beyond a bearer token.

We used [FileBrowser Quantum](https://github.com/gtstef/filebrowser), a self-hosted file manager that exposes a clean REST API. It mounts your network shares as named "sources" and lets you list, read, search, download, and write files through standard HTTP calls.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Office / LAN                                               │
│                                                             │
│  \\fileserver\data   (SMB/CIFS)                             │
│          │                                                  │
│          │  mount                                           │
│          ▼                                                  │
│  Linux VM  /srv/nas_data                                    │
│          │                                                  │
│          │  volume mount                                    │
│          ▼                                                  │
│  ┌──────────────────────┐                                   │
│  │  FileBrowser Quantum │  :8080                            │
│  │  Docker container    │                                   │
│  └──────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│  nginx  :443  ──── Cloudflare ────▶  files.example.com     │
└─────────────────────────────────────────────────────────────┘
                                            │
                         ┌──────────────────┤
                         │                  │
                         ▼                  ▼
              Claude Code / API      Claude Desktop (Windows)
              (direct HTTP calls)    ┌────────────────────┐
                                     │  filebrowser-mcp   │
                                     │  local Node.js     │
                                     │  stdio MCP server  │
                                     └────────────────────┘
```

The file server host can be set up in two ways:

- **Cloud VM with VPN or peering into the LAN**: the VM mounts the SMB share over a private tunnel; only the HTTPS endpoint is public-facing.
- **Office server with a port exposed**: FileBrowser runs directly on a machine that already has access to the share; nginx (or a reverse proxy like Cloudflare Tunnel) exposes only port 443 to the internet.

Either way, FileBrowser Quantum runs as a Docker container and mounts the share as a local path. nginx sits in front, terminates TLS via Cloudflare, and enforces an IP allowlist. The whole stack is reachable at `https://files.example.com`.

AI agents on any network (a cloud VM, a remote laptop, a Windows desktop) reach the file server through that HTTPS endpoint.

---

## Setting Up FileBrowser Quantum

### 1. Mount the SMB share on the Linux host

```bash
# /etc/fstab entry
//192.168.1.100/data  /srv/nas_data  cifs  credentials=/etc/smbcredentials,uid=1000,gid=1000,file_mode=0664,dir_mode=0775  0  0
```

The `uid`/`gid` and mode flags are important. They ensure the Docker container (running as a non-root user) can both read and write files.

### 2. docker-compose.yaml

```yaml
services:
  filebrowser:
    image: gtstef/filebrowser:stable
    container_name: filebrowser
    ports:
      - "8080:80"
    volumes:
      - /srv/nas_data:/nas:rw
      - /opt/filebrowser/data:/config
    environment:
      - FB_DATABASE=/config/database.db
      - FB_CONFIG=/config/config.yaml
    restart: unless-stopped
```

### 3. config.yaml: define sources

```yaml
sources:
  - name: main
    path: /nas
```

You can define multiple sources if you have more than one share.

---

## REST API at a Glance

Once running, the API is straightforward:

```bash
TOKEN="<your-jwt-token>"

# List a folder
curl "https://files.example.com/api/resources?source=main&path=/CLIENTS" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Read a text file
curl "https://files.example.com/api/resources?source=main&path=/CLIENTS/acme/notes.txt&content=true" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Download a binary file (PDF, xlsx, etc.) — note: file= not path=
curl "https://files.example.com/api/resources/download?source=main&file=/CLIENTS/acme/report.xlsx" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN" \
  --output report.xlsx

# Search by filename
curl "https://files.example.com/api/tools/search?source=main&query=tax+return+2024" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN"

# Write a file
curl -X POST "https://files.example.com/api/resources?source=main&path=/CLIENTS/acme/summary.txt&override=true" \
  -H "Cookie: filebrowser_quantum_jwt=$TOKEN" \
  -H "Content-Type: text/plain" \
  --data "AI-generated summary goes here"
```

> **Gotcha:** The download endpoint uses `file=` as the query parameter, not `path=`. Using `path=` returns `{"status":400,"message":"no files specified"}`. This inconsistency is worth documenting. It tripped us up initially.

---

## Security Measures

Opening file server access to the internet requires deliberate controls. Here is what we applied, from most to least important.

### 1. Scoped, long-lived JWT tokens

FileBrowser Quantum supports issuing named API tokens with explicit permission sets embedded in the JWT payload. We created a dedicated `ai` user with only the capabilities the agent actually needs:

```json
{
  "Permissions": {
    "api":      true,
    "modify":   true,
    "create":   true,
    "download": true,
    "share":    true,
    "delete":   false,
    "admin":    false
  }
}
```

**Delete is disabled.** An AI agent that can delete files is a data-loss risk: one hallucinated path and important client files are gone. Write access is sufficient for almost every automation use case. If you genuinely need deletion, do it through a separate, human-triggered workflow.

The token is set to expire in ~3 years. Long enough that it does not need babysitting, short enough that it will eventually rotate.

### 2. Removing delete: the BoltDB patch

FileBrowser Quantum stores user records in a BoltDB (key-value) database. The standard HTTP API for updating user permissions (`PUT /api/users?id=N`) had a quirk in our version: it always reset all permissions to false. We had to patch the database directly.

We wrote a small Go script that:
1. Stopped the Docker container to release the exclusive BoltDB lock.
2. Opened the database directly using the `bbolt` library.
3. Located the user record by its big-endian uint64 key.
4. Decoded the JSON user record, set `permissions.delete = false`, and cleared the `tokens` field (to invalidate any old tokens that still had delete enabled).
5. Wrote the record back, verified it in the same transaction, then restarted the container.

The `tokens` field step is critical. FileBrowser embeds the full permission set inside the JWT itself. If an old token with `delete: true` is still stored in the user record, the server restores those permissions on startup, overriding your DB change. Clearing `tokens` forces the server to issue fresh tokens reflecting the updated permissions.

### 3. nginx IP allowlist

The public URL is fronted by nginx, which checks the real client IP (passed through by Cloudflare via `X-Forwarded-For`) against an allowlist:

```nginx
geo $allowed_ip {
    default         0;
    200.0.13.10    1;   # office static IP
    2004:ab8::/48   1;   # authorised IPv6 prefix
}

server {
    listen 443 ssl;
    server_name files.example.com;

    if ($allowed_ip = 0) {
        return 403;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}
```

If a request comes from an unknown IP, even with a valid token, nginx returns 403 before FileBrowser ever sees the request. This means a leaked token is useless from outside the authorised IPs.

For AI agents running on cloud VMs, add their static IPs or CIDR prefix to the allowlist.

### 4. HTTPS only via Cloudflare

All traffic goes through Cloudflare, which handles TLS termination and provides DDoS protection. The origin (nginx) only accepts connections from Cloudflare's IP ranges, so the raw VM IP is not directly reachable on port 443.

---

## Wiring It Into Claude Desktop via MCP

For Claude Desktop on Windows (where you want the agent to work with local files after downloading them), we added a local [MCP](https://modelcontextprotocol.io/) server. The MCP server is a small Node.js process that wraps the FileBrowser HTTP API as MCP tools, communicating with Claude Desktop over stdio.

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "workspace": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Tools\\filebrowser-mcp\\index.js"],
      "env": {
        "FILEBROWSER_URL": "https://files.example.com",
        "FILEBROWSER_TOKEN": "<token>"
      }
    }
  }
}
```

The MCP server exposes these tools to the agent:

<Table data={
    {
        headers: ['Tool', 'Purpose'],
        rows: [
            ['fs_list_sources', 'List available drives'],
            ['fs_list_folder', 'Browse a folder'],
            ['fs_read_file', 'Read text file content'],
            ['fs_download_file', 'Download binary file to local temp folder'],
            ['fs_search_files', 'Search by filename'],
            ['fs_get_file_metadata', 'Get size / date / type'],
        ]
    }
} />

The key tool here is `fs_download_file`. Claude's `web_fetch` tool cannot pass custom headers, so it cannot supply the auth cookie. The local MCP server, running as a native process with the token in its environment, has no such restriction. It fetches the file over HTTPS and saves it to the Windows temp folder, returning the local path so Claude can then read it with normal file tools.

```javascript
async function downloadFile({ source, path, save_to }) {
  // note: download endpoint uses file= not path=
  const url = `/api/resources/download?source=${encodeURIComponent(source)}&file=${encodePath(path)}`;
  const res = await fbFetch(url);
  const buffer = await res.arrayBuffer();
  const filename = path.split("/").pop();
  const localPath = save_to || join(tmpdir(), filename);
  writeFileSync(localPath, Buffer.from(buffer));
  return { source, path, filename, local_path: localPath, size_bytes: buffer.byteLength };
}
```

---

## Why This Works Better Than Alternatives

Claude does provide built-in connectors for services like Dropbox and OneDrive. In practice, though, most organisations have multiple accounts spread across different purposes: a Dropbox for one team, an OneDrive for another, a legacy NAS for a third. Each connector needs its own authorisation flow and only covers one account at a time.

An HTTP file server flips this: you mount every share behind a single endpoint, define named sources, and the agent accesses all of them through one token and one API. No per-account OAuth dance, no switching contexts.

<Table data={
    {
        headers: ['Approach', 'Trade-off'],
        rows: [
            ['VPN', 'Requires credential management; gives the agent broad network access'],
            ['Cloud sync connectors (Dropbox, OneDrive)', 'One connector per account; multiple accounts across teams means multiple authorisation flows to manage'],
            ['Direct SMB exposure', 'SMB was not designed for internet exposure; serious security risks'],
            ['HTTP file server (this setup)', 'Single endpoint, multiple sources; scoped token; IP allowlist; works for cloud storage and on-prem shares alike'],
        ]
    }
} />

The HTTP approach is universally accessible because every AI agent, whether it is Claude Code running on a cloud VM, Claude Desktop on a Windows workstation, or an API-driven automation script, already knows how to make HTTP requests. No special drivers, no OS-level mounts, no VPN configuration.

---

## Summary

If you have an office NAS that AI agents need to reach:

1. **Deploy FileBrowser Quantum** (or any HTTP file server) on a VM that can mount the share.
2. **Issue a scoped token**: read/write, no delete, fixed expiry.
3. **Lock it down at the network layer**: nginx IP allowlist, TLS via a CDN.
4. **For Claude Desktop**, add a local MCP server that wraps the HTTP API, so the agent can download binary files it could not otherwise fetch (PDFs, spreadsheets, etc.).

The result is an AI agent that can list folders, search for files, read documents, write results back, and download any file type, from any network, without ever needing a VPN or direct NAS access.

95f1a970be11f488ed5a78156ee4a05b6bcd8ad53213a343711a0b6c0febb763

A practical walkthrough of deploying FileBrowser Quantum as an HTTP gateway over SMB network shares, issuing scoped long-lived JWT tokens, and wiring the API into Claude Desktop via a local MCP server, so AI agents can access office files without VPN or physical LAN access.

Claude Cowork (and similar browser-based AI agents) can browse web pages but cannot reach SMB/CIFS network shares. Here is how we wrapped our office NAS in an HTTP API so the agent can list, read, search, and write files from anywhere, with proper security controls.

Tag: Mcp

Tag: Mcp

Introducing Parley: Broker-Agnostic Messaging for AI Agents

Giving AI Agents Access to Network Drives via an HTTP File Server