Interfaces

Handrive is designed AI-native and cluster-native from the ground up. Every feature is accessible through multiple interfaces, enabling both human users and AI agents to manage files seamlessly across unlimited devices.

Mental model: Handrive works like SMB/NFS network file sharing on your OS, but over the internet. You connect to a contact, then see their shared folders. Files transfer directly between devices — never through servers. Your email is your identity; contacts are your connections (one contact = access to all their devices). To share: create a share from any folder, then add members by email with roles (viewer/editor/admin). To receive: add the sharer as a contact, then discover their shares.

MCP

Model Context Protocol for AI assistants. Connect Claude, GPT, and other AI agents directly to your files.

stdioHTTP SSE

REST API

Full HTTP API with OpenAPI documentation. Build custom integrations and automate workflows.

OpenAPI 3.0Swagger UI

CLI

Command-line interface for scripting and automation. Interactive and non-interactive modes.

macOSLinuxWindows

Desktop

Native GUI application for everyday use. Visual file management with drag-and-drop support.

macOSWindowsLinux

Architecture

All interfaces share the same core engine. The REST API is the foundation — both MCP and CLI are clients of the REST API. This ensures consistent behavior across all interfaces.

┌─────────────────────────────────────────────────────────────┐
│                        AI Agents                            │
│              (Claude, GPT, Custom Agents)                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    MCP Server                               │
│            ┌─────────────┬─────────────┐                    │
│            │   stdio     │  HTTP SSE   │                    │
│            │  transport  │  transport  │                    │
│            └─────────────┴─────────────┘                    │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    REST API                                 │
│                  (OpenAPI 3.0)                              │
│    ┌─────────┬─────────┬──────────┬──────────┬─────────┐   │
│    │  Auth   │ Shares  │  Files   │ Transfers│  Users  │   │
│    └─────────┴─────────┴──────────┴──────────┴─────────┘   │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   Handrive Core                             │
│         P2P Engine │ Storage │ Encryption │ Sync           │
└─────────────────────────────────────────────────────────────┘

MCP (Model Context Protocol)

MCP enables AI assistants to interact with Handrive using natural language. The MCP server exposes 40+ tools covering all Handrive operations.

Transports

TransportUse CaseCommand
stdioLocal AI agents (Claude Desktop)hand mcp
HTTP SSERemote AI agents, web integrationshand serve (port 4263)

Example: Claude Desktop Configuration

{
  "mcpServers": {
    "handrive": {
      "command": "/path/to/hand",
      "args": ["mcp"]
    }
  }
}

Full MCP Guide →

REST API

The REST API provides complete programmatic access to Handrive. All endpoints are documented with OpenAPI 3.0 and include a Swagger UI for interactive exploration.

Base URL

http://127.0.0.1:4263/api

Key Endpoints

CategoryEndpoints
AuthPOST /auth/otp/request, POST /auth/otp/verify, GET /auth/status
SharesGET /shares, POST /shares, GET /shares/:id
FilesGET /shares/:id/files, POST /shares/:id/files/search
TransfersGET /transfers, POST /transfers/download, POST /transfers/upload
MembersGET /shares/:id/members, POST /shares/:id/members

OpenAPI Documentation

When the server is running, visit http://127.0.0.1:4263/api/docs for interactive API documentation.

CLI

The CLI provides both interactive commands for humans and non-interactive commands for automation and AI agents.

Interactive vs Non-Interactive

ModeExampleUse Case
Interactivehand auth login otp emailHuman users (prompts for input)
Non-Interactivehand auth otp verify email codeScripts, AI agents (no stdin)

Full CLI Reference →

Desktop App

The desktop app provides a visual interface for file management. It runs the same core engine as the CLI and can be used alongside AI agents.

File Management

  • Grid and list view modes
  • Search files across shares
  • Star/favorite files for quick access
  • Sort by name, size, or date
  • Create folders, rename, and delete files
  • Tag files with custom labels
  • File info panel with metadata

Transfers

  • Upload files to remote shares
  • Download from remote shares
  • Real-time progress with speed and ETA
  • Cancel, restart, and clear transfers
  • Transfer history and status tracking

Collaboration

  • Create shares from local folders
  • Add members with viewer/editor roles
  • Contact management and discovery
  • Invite new users via email

Settings

  • REST API server toggle (port 4263)
  • MCP configuration for Claude Desktop/Code
  • Light/dark theme
  • Multi-language support (EN, ZH, JA, KO, DE, FR, ES)

Download Desktop App →

Choosing an Interface

Use CaseRecommended
AI agent integration (local)MCP stdio — Direct connection to Claude Desktop
AI agent integration (remote)MCP HTTP or REST API
Shell scripts / automationCLI — Non-interactive commands
Custom applicationREST API — Full programmatic control
Everyday file sharingDesktop — Visual drag-and-drop
Headless server / NASCLI + REST API

See Also