Onclave

Onclave is a Pi extension for secure LAN discovery, explicit trust, and prompt routing between Pi sessions on trusted machines.

Note

This project expands on IndyDevDan's Pi coding agent extension work for two-way communication between agents and takes it further into secure LAN discovery, explicit machine trust, and authenticated cross-host messaging. Watch his video here: Pi coding agent extension with two-way agent communication

What It Does

• starts or reuses one local machine hub per host;
• discovers peer hubs on the LAN over UDP broadcast;
• requires explicit Ed25519 trust exchange before remote access is allowed;
• routes prompts and responses over authenticated WSS connections;
• supports static peers when UDP discovery is unavailable;
• shows peer status directly in Pi with a compact widget.

Development Prerequisites

Before installing dependencies in a fresh environment, run the bootstrap preflight that matches your shell:

PowerShell

pwsh -File ./scripts/preflight.ps1

Bash / Git Bash / WSL / Linux / macOS

bash ./scripts/preflight.sh

These bootstrap scripts check for the required repo tools (node, pnpm, just, git) and report whether pi is available for local extension loading.

Once bootstrap passes, you can also run the repo-aware Node check:

just preflight-repo

Repository-wide environment and package standards live in:

• Development Environment and Monorepo Package Requirements

Quick Start

From this repository, the happy developer path is:

bash ./scripts/preflight.sh
just setup
just check
just pi-local

• bash ./scripts/preflight.sh checks bootstrap tool and workspace readiness.
• just setup installs dependencies with pnpm.
• just check runs typecheck and tests.
• just pi-local starts Pi with ./extensions/onclave-comms loaded.

For a named local session, run Pi directly:

pi -e ./extensions/onclave-comms --name host-a

Install the Pi Extension

Use one of these install/load paths depending on what you are trying to do.

Local development load

Use this while working in this repo:

bash ./scripts/preflight.sh
just setup
just pi-local

Equivalent direct Pi command:

pi -e ./extensions/onclave-comms

Local package install

Use this to test package metadata from a local checkout:

pi install .

Git package install

Use this to install from a Git remote:

pi install git:git@github.com:traefikturkey/onclave.git

After installing from a local path or Git URL, start Pi normally and run:

onclave_status

Loading extensions/onclave-comms directly is supported when the directory remains inside this repo checkout.

Then inside Pi:

onclave_status
onclave_agents
onclave_peers

If you want help preparing a host for manual acceptance testing:

pnpm run onclave:acceptance-host -- --host-name host-a

Documentation

• Development Environment - repository-wide tool, package, dependency, and preflight standards for the monorepo
• Usage Guide - quick starts, extension loading, flags, status dots, and tool examples
• Operator Guide - runtime state, trust exchange, discovery, messaging, and troubleshooting
• Manual Acceptance - step-by-step host-to-host validation flow
• Status - implementation progress and delivered scope
• Design Decisions - key v1 design choices
• onclave-comms Requirements - original communication extension requirements and success criteria

Current Usage Model

1. Start Pi with extensions/onclave-comms loaded from inside this repo checkout.
2. Run onclave_status to initialize or reuse the local hub.
3. Exchange ssh-ed25519 public key lines with trusted peers.
4. Use onclave_peers and onclave_remote_agents to find reachable remote sessions.
5. Use onclave_send or onclave_remote_send to route prompts.

For the full tool reference and examples, start with docs/extensions/onclave-comms/README.md.