Dispatch

A local agent that lets trusted people send structured, human-approved action requests to another person's device.

How it works

1. Sender composes a dispatch (e.g. "open this URL", "clone this repo") on the dashboard
2. Recipient receives it, reviews the actions, and approves or declines
3. If approved, the local agent executes the actions on the recipient's machine

Trust relationships must be established before dispatches can be sent. All dispatches are signed with Ed25519 keys.

Architecture

• agent/ — Python local agent with 8 action handlers (open URL, clone repo, install package, etc.)
• server/ — FastAPI async server with PostgreSQL, JWT auth, WebSocket updates
• dashboard/ — Next.js 14 web dashboard with shadcn/ui
• shared/ — Canonical dispatch JSON schema

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• Docker & Docker Compose (for PostgreSQL and Redis)

Note: If you have a local PostgreSQL running on port 5432 (e.g. via Homebrew), stop it first: brew services stop postgresql@15

1. Start the database

docker-compose up -d db redis

This starts PostgreSQL on port 5432 and Redis on port 6379.

2. Set up the server

pip install -r server/requirements.txt

# Run database migrations (creates tables)
PYTHONPATH=. python3 -c "
import asyncio
from server.db import engine, Base
from server.models import *
async def init():
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
asyncio.run(init())
"

# Start the server
PYTHONPATH=. python3 -m uvicorn server.main:app --host 0.0.0.0 --port 8000

Server runs at http://localhost:8000. API docs at http://localhost:8000/docs.

3. Set up the dashboard

cd dashboard
npm install
npm run dev

Dashboard runs at http://localhost:3000.

4. Start the local agent

The agent runs on the recipient's machine and executes approved dispatches.

pip install -r agent/requirements.txt

# Run in daemon mode — connects to server, polls for dispatches, and executes approved ones
PYTHONPATH=. python3 -m agent daemon --server http://localhost:8000 --email RECIPIENT_EMAIL --password RECIPIENT_PASSWORD

# Or run a single dispatch file locally (no server needed)
PYTHONPATH=. python3 -m agent local test_dispatch.json

The agent supports two approval flows:

• Dashboard approval: Approve dispatches from the Inbox page in the web dashboard. The agent detects the approval and executes automatically (no pop-up).
• Native approval: If a dispatch hasn't been approved via the dashboard, the agent shows a native pop-up window for review and approval.

5. LAN access (optional)

To let someone on the same Wi-Fi network use the dashboard:

# Find your local IP
ipconfig getifaddr en0   # macOS

# Create dashboard/.env.local with:
NEXT_PUBLIC_API_URL=http://YOUR_IP:8000
NEXT_PUBLIC_WS_URL=ws://YOUR_IP:8000

# Add your IP to CORS in server/main.py allow_origins list
# Restart both server and dashboard

Your friend can then open http://YOUR_IP:3000 in their browser.

Note: macOS firewall may block incoming connections. Check System Settings > Network > Firewall.

Usage Flow

1. Register two accounts on the dashboard (http://localhost:3000) — use two browser windows or regular + incognito
2. Send a trust request from the sender to the recipient's email on the Recipients page
3. Log in as the recipient and approve the trust request
4. Log in as the sender and compose a dispatch on the Compose page
5. The recipient sees the dispatch in their Inbox page and can approve or decline
6. The agent (if running) picks up the approved dispatch and executes the actions on the recipient's machine

Action Types

Type	Description
open.url	Opens a URL in the default browser
clone.repo	Clones a git repository
install.package	Installs a package via brew/apt/pip/npm
set.env	Sets an environment variable
write.config	Writes a config file
download.file	Downloads a file from a URL
fetch.and.extract	Downloads and extracts an archive
install.app	Installs a macOS/Linux application

Security

• Ed25519 dispatch signing and verification
• URL allowlist for app downloads
• VirusTotal hash checking
• macOS codesign verification
• Path traversal sanitization
• Nonce replay protection
• JWT access + refresh tokens with bcrypt password hashing