Peta Desk – MCP Desktop Client & Approval Console

Peta Desk is a cross‑platform desktop application (typically implemented with Electron) that provides a user‑facing control surface on top of Peta Core. It is the human-in-the-loop approval console and desktop companion for Peta Core’s MCP vault and gateway (“1Password for AI agents”). It connects to the gateway’s Socket.IO and MCP endpoints.

It runs as the desktop companion to Peta Core, acting as a secure client and approval surface for AI agents: users can see what agents are allowed to do, configure which MCP servers they can touch, and approve or deny risky operations before they run.

The application ships with an embedded Node/Electron runtime and a statically exported Next.js frontend, so packaged builds are fully self‑contained.

📘 Full Documentation → https://docs.peta.io
🚀 Download / Official Website → https://peta.io

---

Table of Contents

• About the Project
  • What is Peta Desk?
  • Key Use Cases
  • Interaction Model
• Project Structure
  • Directory Layout
  • Main Components
• Architecture Highlights
• Getting Started
  • Prerequisites
  • First-time Setup
  • Running in Development
  • Building & Packaging
• API Overview
  • Electron API
  • Electron API Legacy
  • Socket.IO API
  • Communication Model
  • Runtime Behavior
• Troubleshooting
• Contributing
• License

---

About the Project

What is Peta Desk?

Peta Desk is a cross‑platform desktop client (Windows, macOS, and Linux) that exposes a user‑friendly control surface for Peta Core. It is the human-in-the-loop desk for Peta Core’s MCP vault and gateway: it connects to the gateway’s Socket.IO and MCP endpoints and operates as a desktop companion to Peta Core, acting as a secure client and approval surface for AI agents.

Key Use Cases

• Capability configuration

  • Display the tools, resources, and prompts currently available to the user.
  • Allow users to further restrict their own capabilities on a per‑client basis.
  • Apply updates in real time when administrators change permissions.

• Server configuration

  • Allow users to configure servers that require their own credentials (for example, personal API keys), without hand-editing JSON config files.
  • Unconfigure or revoke previously stored user configuration.
  • Automatically trigger server startup once configuration is complete.

• Approval workflow

  • Receive approval requests when an agent triggers a tool that requires human review, before Peta Core forwards it to downstream MCP servers.
  • Show the parameters the agent intends to send.
  • Let the user approve, reject, or modify the request before Peta Core forwards it to downstream MCP servers.

Interaction Model

Peta Desk communicates over two primary channels:

• Socket.IO
  Used for capability updates, approval requests, and general notifications.

• MCP
  Used for the actual tool calls executed by the agent.

The same Socket.IO API can be consumed from other applications if you want to build a custom user or admin UI.

---

Project Structure

Directory Layout

peta-desk/
├── electron/                  # Electron main process
│   ├── main.js                # Main process entry
│   ├── preload.js             # Preload script with IPC bridge
│   ├── socket-client.js       # Socket.IO connection manager
│   ├── biometric-auth.js      # Touch ID / Windows Hello integration
│   ├── password-manager.js    # Master password encryption
│   └── mcp-config-manager.js  # External app config file manager
├── frontend/                  # Next.js frontend
│   ├── app/                   # Next.js App Router pages
│   │   ├── (onboarding)/      # Setup flow screens
│   │   ├── (dashboard)/       # Main dashboard interface
│   │   ├── quick-panel/       # Fast access panel
│   │   └── security-authorization/ # Auth flow
│   ├── components/            # Reusable UI components
│   ├── contexts/              # React contexts (socket, auth)
│   └── out/                   # Static export for Electron packaging
├── dist/                      # electron-builder output (DMG/EXE/AppImage)
├── docs/                      # Technical documentation
├── install-deps.js            # Helper script to install dependencies
└── package.json               # Root scripts for dev, build, and packaging

Main Components

• Electron main process (electron/main.js)

  • Manages application lifecycle, windows, tray icon, and native menus.
  • Handles Socket.IO connections to remote Peta Core servers.
  • Manages biometric authentication (Touch ID on macOS, Windows Hello on Windows).
  • Encrypts and stores master password and access tokens.
  • Reads/writes MCP configuration files for external apps (Claude, Cursor, VSCode, Windsurf).
  • Implements custom URL scheme handler (petadesk://).
  • Single instance lock enforcement.

• Socket.IO client (electron/socket-client.js)

  • Manages WebSocket connections to Peta Core gateway.
  • Handles multi-server connections with per-server state tracking.
  • Auto-reconnect with exponential backoff.
  • Notification system for approval requests and capability updates.

• MCP configuration manager (electron/mcp-config-manager.js)

  • Reads and modifies MCP config files for external applications.
  • Platform-aware path resolution (macOS, Windows, Linux).
  • Adds/removes/updates server configurations in JSON config files.
  • Enables integration with Claude Desktop, Cursor, VSCode, and Windsurf.

• Security modules

  • biometric-auth.js: Platform-specific biometric authentication.
  • password-manager.js: Implements the local credential vault. Derives an encryption key from the master password using PBKDF2 and encrypts tokens/credentials with AES-GCM so plaintext values never hit disk and never leave the device.

• Preload script (electron/preload.js)

  • Context-isolated bridge between renderer and main process.
  • Exposes secure APIs: electronAPI, electron, socketIO.
  • Handles Socket.IO connections directly in preload to preserve full features.
  • Patches fetch/XHR for static file protocol compatibility.

• Frontend (frontend/)

  • Next.js 15 App Router with React 19.
  • TailwindCSS + shadcn/ui components.
  • Onboarding flow: Welcome → Master Password → Auto-Lock → MCP Setup.
  • Dashboard: Server management, capability configuration, approval handling.
  • Zustand state management with localStorage persistence.

• Distribution artifacts (dist/)

  • macOS: dist/MCP Desktop-*.dmg
  • Windows: dist/MCP Desktop Setup *.exe
  • Linux: dist/MCP Desktop-*.AppImage

---

Architecture Highlights

• Human-in-the-loop approval console for Peta Core’s MCP vault and gateway, so humans stay in control of risky agent actions.
• Cross‑platform desktop client targeting Windows, macOS, and Linux from a single codebase.
• Socket.IO-based communication with remote Peta Core servers for real-time updates.
• Security-first design with biometric authentication, master password encryption, and token encryption (AES-GCM).
• Local credential vault with a master key – access tokens and per-user credentials are encrypted with a key derived from a user-chosen master password (PBKDF2 + AES-GCM); plaintext secrets never hit disk and never leave the device.
• Multi-server support – manage multiple Peta Core instances simultaneously with per-server state tracking.
• External app integration – automatically configures MCP settings for Claude Desktop, Cursor, VSCode, and Windsurf.
• Local backup system – create, restore, and manage configuration backups with metadata.
• Fully bundled app with embedded Node.js/Electron runtime – no system dependencies required for end users.
• Modern tech stack: Next.js 15, React 19, TypeScript, TailwindCSS, shadcn/ui, Zustand.
• Context-isolated IPC between renderer and main process for security.
• Auto-lock timer with configurable intervals (5 min, 15 min, 30 min, 1 hour, never).
• Team-ready & customizable – because Peta Desk is open source, teams can fork it, add their own logo/branding or SSO flows, and still rely on the same master-key-based encryption model.

---

Security & Encryption Model

Peta Desk is designed so that sensitive values are either:

• stored in Peta Core’s server-side vault, or
• stored locally on the user’s machine, encrypted with a master key the user controls.

Local master key

• During onboarding, the user chooses a master password; a key is derived from it using PBKDF2 (HMAC-SHA-256).
• Access tokens and per-user credentials are encrypted with AES-256-GCM before they are written to disk.
• The master key and raw secrets never leave the device and are never sent to Peta Core.
• On supported platforms, biometric APIs (Touch ID / Windows Hello) can unlock the local vault without retyping the password.

This model lets teams distribute Peta Desk internally—or fork and rebrand it with their own logo and integrations—without changing the underlying security properties.

---

Getting Started

Prerequisites

To build and run Peta Desk from source, you will need:

• Node.js v18.17+ for development and packaging.
• npm (or a compatible package manager).
• A recent Electron toolchain.
• (Optional) A running Peta Core instance if you want to connect to a secure gateway.

End users of the packaged app do not need Node.js installed.

First-time Setup

From the repository root:

1. Install dependencies

   # Recommended: auto installer (installs root + frontend)
   node install-deps.js
   
   # Manual install
   npm install
   cd frontend && npm install
   cd ..
   

2. Prepare the frontend build (if you want a production/static export) The build scripts below typically handle this for you, but you can also run it manually:

   cd frontend
   npm run build      # Next.js production build
   # Optional: export to static files if your config uses it
   # npm run export
   cd ..
   

Running in Development

A typical development loop looks like this:

1. Run the integrated dev script (Next.js + Electron)

   npm run dev
   

   The script picks an available port (prefers 34327–34329), starts the Next.js dev server there, then launches Electron pointed at that port. Check the terminal output for the exact URL.

Building & Packaging

Peta Desk uses shell scripts and npm scripts to produce signed and unsigned cross‑platform desktop builds for Windows, macOS, and Linux.

Dev / Unsigned builds

Use these flows when you just need an unsigned binary for local testing:

# Preferred: includes asset path fixes and static export
./build-production.sh

# Base version without extra path handling
./build-nosign.sh

# Manual environment toggle for unsigned builds
export CSC_IDENTITY_AUTO_DISCOVERY=false
npm run build

If the packaged app shows a blank window, prefer `./build-pr