Metadata-Version: 2.4
Name: unitport
Version: 0.0.5
Summary: UnitPort local helper — headless daemon bridging local Isaac Lab / MuJoCo / resources to the UnitPort cloud canvas.
Author: UnitPort
License: Proprietary
Project-URL: Homepage, https://unitport.ai
Keywords: unitport,isaac-lab,mujoco,reinforcement-learning,robotics
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: websockets>=12
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# 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`.
