Barehands Python Server Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Barehands system serves as the "body" or physical interface for J.A.R.V.I.S., focusing on hand-tracking capabilities and a "glass board" visual stage. While originally architected around a Python-based server (server.py), the current implementation in this repository utilizes a TypeScript-based integration that mirrors the original Python behavior to maintain compatibility with existing hand-tracking assets and front-end logic.
Sources: backend/src/barehands/sample-notes/Getting Started/Wire In Your AI.md, backend/src/barehands/server.ts:13-18
Architecture and Core Logic
The Barehands integration functions as a loopback-only service, typically listening on port 8794. It acts as a bridge between the J.A.R.V.I.S. agent loop and the visual "stage" rendered in an Electron webview. The server manages two primary communication channels: the "Ring" (semantic status) and the "Board" (content stage).
The Dual-State Mechanism
The server employs a hybrid state management system. It maintains a liveOrbState mirror fed directly by the J.A.R.V.I.S. agent loop, while simultaneously supporting a legacy file-based polling system for backward compatibility with the original Python implementation.
Sources: backend/src/barehands/server.ts:13-22, CONTRIBUTING.md:42
System Flow
The following diagram illustrates how the Barehands server integrates with the Desktop environment and the Agent backend.
The diagram shows the bidirectional flow where the Agent updates the server's state, which is then polled by the Stage UI.
Sources: backend/src/barehands/server.ts:13-22, 137-145, backend/src/handler.ts:474-477
Component Breakdown
1. The Ring (Visual Identity)
The "Ring" represents the AI's face and state. The server provides state information via the /barehands/orb endpoint (aliased from /orb).
| State | Purpose | Default Source |
|---|---|---|
idle | Core initialized, waiting | state/state or Live Mirror |
listening | Microphone active | state/state or Live Mirror |
thinking | Model inference active | state/state or Live Mirror |
speaking | Response output active | state/state or Live Mirror |
Sources: backend/src/barehands/server.ts:109-135, backend/src/barehands/sample-notes/Getting Started/Wire In Your AI.md
2. The Board (Command Stage)
The "Board" is a stage where content is materialized. Commands are sent via POST requests to /barehands/cmd.
| Action | Description | Parameter Example |
|---|---|---|
add_card | Materializes a glass card | {"title":"IDEA", "body":"..."} |
add_img | Displays an image from media airlock | {"src":"misc/chart.png"} |
hand | Delivers a 3D model (.glb) | {"src":"models/engine.glb"} |
yank | Removes a card from the board | {"title":"IDEA"} |
explode | Disassembles a 3D model | N/A |
Sources: backend/src/barehands/sample-notes/Getting Started/Wire In Your AI.md, backend/src/barehands/server.ts:80-83, 161-178
API Endpoints and Configuration
The server exposes a set of REST endpoints that mirror the legacy Python API while adding modern J.A.R.V.I.S. bridge capabilities.
Configuration (barehands.json)
The system is configured via a JSON file that defines the assistant name and data "Orbs" (folders for notes or media).
{
"name": "Assistant",
"port": 8794,
"orbs": [
{ "title": "Notes", "path": "sample-notes", "kind": "notes" },
{ "title": "Props", "path": "media", "kind": "media" }
]
}
Sources: backend/src/barehands/server.ts:24-32, backend/src/barehands/sample-notes/Field Guide/Make It Yours.md
Key API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/barehands/health | GET | Returns service status and version. |
/barehands/config | GET | Provides the current name and orb list. |
/barehands/orb | GET | Returns current state, mood, and audio wave data. |
/barehands/tree | GET | Lists markdown notes for a specific orb index. |
/barehands/props | GET | Lists media files in the props airlock. |
/barehands/cmd | POST | Submits a board command for execution. |
/jarvis/bridge | POST/GET | Exchanges events between Barehands and the Desktop UI. |
Sources: backend/src/barehands/server.ts:101-110, 147-159, 180-194, 218-249, 251-280
Security and Filesystem Integration
Media Airlock and Jailing
The server implements a "Media Airlock" pattern. Only files within the defined media root can be served or referenced in commands. A jailCheck function ensures that any requested path is strictly contained within the allowed directory to prevent path traversal.
function jailCheck(target: string, jail: string): boolean {
const resolved = resolve(target);
const resolvedJail = resolve(jail);
const sep = require("node:path").sep;
return resolved.startsWith(resolvedJail + sep) || resolved === resolvedJail;
}
Sources: backend/src/barehands/server.ts:70-76, 78-99
Lifecycle Management
In the J.A.R.V.I.S. Desktop application, the Barehands service is managed as a child process or integrated module. The Electron main process handles the initialization and ensures the service binds correctly to port 8794, retrying if the port is busy.
Sources: src/main.ts:316-368
Conclusion
The Barehands integration represents the physical manifestation of the J.A.R.V.I.S. agent, providing a tactile, hand-tracked interface. By mirroring the original Python server's API in a TypeScript environment, the project maintains compatibility with specialized hand-tracking assets while allowing for deep integration into the Electron-based Desktop Control Room. This synergy enables the AI to "stage" information visually on a virtual glass board in response to complex user queries.
Sources: backend/src/barehands/sample-notes/Getting Started/Wire In Your AI.md, backend/src/handler.ts:333-348