unitport 0.0.4

UnitPort local helper — headless daemon bridging local Isaac Lab / MuJoCo / resources to the UnitPort cloud canvas.

unitport — UnitPort local helper

Headless daemon that connects a local GPU / Isaac Lab host (workstation or the user's own cloud server) to the UnitPort cloud canvas. The canvas is the remote control (遥控器); this process has no GUI — only terminal output.

Authoritative design: ../knowledges/local_helper_design.md (rulings LH-D1…LH-D6, contracts C10 pairing / C11 control protocol).

What it is (and is not)

• Is: an outbound-only WebSocket agent exposing a fixed verb set to the cloud (report capabilities, publish an asset index, receive a bundle from the user's own canvas, start/stop a training run, stream telemetry).
• Is not: a shell, an exec server, or a GUI. The cloud can never send an arbitrary command — only the fixed verbs, only from a paired session of the same account, only bundles that originate from the user's own canvas (least-privilege red line, LH-D4 / C11).

The same binary serves execution target ① (UserServerTarget, user cloud server) and ③ (LocalHelperTarget, local host) — only the host differs (LH-D5).

Install

pip install unitport

Cross-platform (Windows + Linux). Runtime deps: websockets (the live link) and, on Python < 3.11, tomli (TOML reader). Everything else is stdlib.

CLI (headless — everything else is driven remotely from the canvas)

Command	Purpose
unitport login	Browser-approve device pairing; stores a refreshable helper token
unitport up (serve)	Dial out to the cloud relay and serve the fixed verb set
unitport status	Connection / run state, paired account, config summary
unitport config	Declare Isaac/MuJoCo interpreter paths + resource roots
unitport doctor	Fail-loud self-check (interpreters, deps, cloud, token)

There are deliberately no pull / train / push local subcommands — those are remote verbs, triggered from the canvas (C11 §4).

Config

• Config dir: %APPDATA%\unitport\ (Windows) · $XDG_CONFIG_HOME/unitport/ or ~/.config/unitport/ (POSIX). Override with UNITPORT_HOME.
• config.toml — cloud base URL, engine interpreter paths, resource_roots, workspace dir. Human-editable; also managed by unitport config.
• token.json — the helper token (secret; chmod 600 on POSIX). Never printed, never logged.
• device.json — the persistent (non-secret) device_id.

Status

Under active construction (phases LH-P1…LH-P8, Isaac Lab first). See the design doc §12 for the phase map. This tree currently implements the local foundation (config, capability detection, doctor, CLI) plus the pairing/transport clients; the workers/relay Durable Object cloud side lives in ../workers/relay.