A free, open-source, self-hostable control plane for AI remote work and server operations
English | 简体中文
Launch an app from an AI session and inspect it in the built-in browser. [Open the full video](https://docs.thandoff.com/media/mobile/mobile-demo.mp4) or see the [Mobile client guide](https://docs.thandoff.com/en/clients/mobile). For more interface screenshots, see the [Interface and Workbench guide](https://docs.thandoff.com/en/guide/workbench). ## Features - **Multi-node management** — Connect local and remote nodes and inspect their resources and managed instances from one place. - **Managed workspaces** — Create, start, stop, and restore isolated workspaces, with Docker as the primary runtime today. - **Image market and custom images** — Choose from a read-only built-in catalog or separately managed custom images through one instance creation flow. - **Environment templates** — Save a Docker instance's installed tools and container configuration as a node-local reusable environment, then combine it with any project or local-folder workspace. - **AI session center** — View and control sessions across instances with real-time state delivered over WebSocket. - **Repository workflows** — Inspect files, changes, branches, and worktrees, with conservative remote delivery for Git repositories. - **Managed Git credentials** — Scope HTTPS tokens or pinned SSH keys to remotes, use them for one-time provisioning, or retain them for Agent, Terminal, App, and Repository Git commands. - **Chat integrations** — Route messages, approvals, and actions from Telegram, DingTalk, WeChat, and Feishu/Lark to a selected instance. - **Application management** — Install, remove, and run applications on target instances through a trusted built-in catalog. - **Mobile client** — Connect an iOS or Android device directly to a user-managed Control Plane for AI sessions, instance operations, applications, and terminals. - **Remote Desktop** — View and control a single window, application, full desktop, or custom region from the web, Desktop, or Mobile. - **Desktop and server deployment** — Run TaskHandoff as a mobile or desktop application, or as systemd services on Debian and Ubuntu. - **English and Chinese UI** — Switch languages instantly or follow the browser language automatically. ## Architecture ```text Browser / Desktop / Mobile / Chat platforms │ ▼ Control Plane UI, API, and chat gateway │ ▼ Node Agent Node resources and instance lifecycle │ ▼ Controlled Instance Workspace, applications, and AI sessions ``` TaskHandoff is organized into three runtime layers: - **Control Plane** provides the Web/API management surface and owns the node inventory, instance board, chat gateway, and cross-instance AI session views. - **Node Agent** runs on each managed machine and owns node-local configuration, runtime resources, folder inventory, and controlled instance lifecycles. Instances continue running when the control plane is stopped or restarted. - **Controlled Instance** hosts a workspace, applications, AI sessions, triggers, and metadata. It can run standalone; in a managed deployment, its lifecycle and access are owned by the Node Agent. Chat and AI Session state form a cross-layer path: the Control Plane owns chat credentials, bindings, command parsing, and routing, while each target AI Session remains the source of truth for conversation state. Docker is the primary isolated runtime and supports multiple instances on one node. A built-in Local Runtime is also available on Windows, macOS, and Linux for one controlled instance per host user. The runtime model is designed to support Kubernetes without duplicating the UI flow, but Kubernetes runtime support is still in development and is not yet a supported deployment target. On Windows nodes, a WSL2 runtime provides a distro-per-instance execution domain alongside Docker and Local. It reuses the same instance API, Node Agent proxy, managed runtime artifact, Git/local-folder workspaces, and recovery path, and is gated behind an explicit node switch for safe rolling upgrades. See [docs/wsl-runtime.md](docs/wsl-runtime.md) for isolation boundaries, the base template build step, and the keep-alive model. ### Environment templates An environment template is a node-local Docker image created from an existing instance with `docker commit`. Registry images and environment templates are peer environment sources in the instance creation flow. Workspace selection remains independent, so either source can be combined with a Git project or a local-folder workspace. Templates capture only the container writable layer, such as installed system packages and tools. They exclude `/workspace`, `/data`, `/home/agent`, every other bind mount or volume, memory, processes, and network state. Derived instances always receive a new identity, registration token, port, and managed volumes. The node agent briefly pauses the source container during commit and rejects a template if Docker Config contains instance-private credentials. Every Docker instance has managed volumes for `/data` and `/home/agent`; Git workspaces also have a managed `/workspace` volume, while local folders use an external bind mount. The instance deletion dialog uses one option, selected by default, to delete all managed data. Clearing it retains every managed volume and reports its name; retained volumes are never attached automatically to another instance. The source node owns both the template record and its Docker image, so a template can be used only on that node while it is ready. Deleting a template removes its internal template tag. A content-addressed internal lease keeps the image recoverable while derived instances reference it, and the image is garbage-collected after the final reference is removed. ## Quick Start ### Requirements - Node.js `>= 24.15.0`, or Bun `>= 1.4.4` for running the services - pnpm `9.15.3` - Docker, when using Docker Runtime, building container images, or running the standalone Compose profile ### Local development ```sh pnpm install pnpm run build:all pnpm cli help ``` Start the Control Plane API and development UI in separate terminals. The disabled authentication mode is intended only for loopback development: ```sh pnpm cli control-plane --auth-mode disabled pnpm run control-plane-ui:dev ``` Common development commands: ```sh # Start the control-plane UI pnpm run control-plane-ui:dev # Type-check and build pnpm run typecheck pnpm run web:typecheck pnpm run build:all # Run tests pnpm test # Inspect the npm package contents pnpm run pack:dry ``` To run a standalone Browser-profile controlled instance instead of the Control Plane development stack: ```sh docker compose up -d --build ``` The current directory is mounted at `/workspace` by default. Set `TASK_HANDOFF_WORKSPACE_HOST` to mount a different host directory. This Compose service is a standalone controlled instance, not a Control Plane and Node Agent deployment. ## Server Deployment Server deployments install the Control Plane and the server-local Node Agent as independent systemd services. The control plane can stop or restart without terminating instances managed by the agent. ### One-line installation On a Debian or Ubuntu server running systemd, run the latest stable installer as root: ```sh curl -fsSL https://github.com/edgestorage/task-handoff/releases/latest/download/install-server.sh | sudo sh ``` The script checks the host, installs Node.js 24 and Docker when needed, installs the latest stable `@task-handoff/server` package from npm, and then creates and starts the Control Plane and Node Agent systemd services. The default `auto` source profile uses Tsinghua APT mirrors and npmmirror for Chinese locale or timezone environments, and also falls back to those mirrors when the official Node.js source is unreachable. Its temporary APT source list does not overwrite the host's source configuration. By default, the control plane listens on port `8081` with password authentication enabled. Installer options can change the port, authentication mode, release channel, and other service settings. The Node Agent and controlled-instance runtime use the same package on either Node.js or Bun. Each process detects its runtime automatically, so no selector is required. Pass `--js-runtime bun` (or set `TASK_HANDOFF_JS_RUNTIME=bun` for a managed container) only when you want to override that detection. Node.js and npm remain required by the current installation, self-update, and node-update paths. Use `--install-source china` or `--install-source official` to select a source profile explicitly: ```sh curl -fsSL https://github.com/edgestorage/task-handoff/releases/latest/download/install-server.sh | sudo sh -s -- --install-source china ``` ### Install with Node.js and Docker already available ```sh sudo npm install -g @task-handoff/server@latest sudo task-handoff install ``` Manage services and updates: ```sh sudo task-handoff start sudo task-handoff stop sudo task-handoff restart task-handoff check sudo task-handoff update ``` The installation creates: ```text task-handoff-node-agent.service task-handoff-control-plane.service ``` See [`scripts/install-server.sh`](scripts/install-server.sh) for supported installer options. ## Connect a Remote Node Remote machines only need the Node Agent. Generate a one-time join token in the Control Plane and prefer the exact installation command shown there. The command downloads the installer from the GitHub repository by default; switch the installer source in the command preview when the target must use the Control Plane's own `/install-node-agent.sh`. Its package version is resolved from the running Control Plane release. The equivalent form is: ```sh curl -fsSL https://raw.githubusercontent.com/edgestorage/task-handoff/main/scripts/install-node-agent.sh | sudo sh -s -- \ --control-plane https://CONTROL_PLANE_HOST \ --join-token JOIN_TOKEN \ --npm-package @task-handoff/node-agent \ --controlled-instance-package @task-handoff/controlled-instance \ --version RELEASE_VERSION ``` On Debian and Ubuntu, the remote-node installer bootstraps the required Node.js 24 and npm on a fresh host. It uses the same automatic source selection; append `--install-source china` to force Chinese mirrors. The selected npm registry is preserved in the Node Agent service environment for subsequent managed updates. Replace `RELEASE_VERSION` with the Control Plane's runtime package version so the Node Agent and controlled-instance runtime use the same release. A standalone Node Agent can update itself without `thctl` or a Control Plane CLI session: ```sh sudo task-handoff-node-agent update --check sudo task-handoff-node-agent update ``` The command uses the `stable` channel by default, asks for confirmation, queues the update, and waits for the service restart to complete. When a local runtime package is installed, it also upgrades the matching `@task-handoff/controlled-instance` version. Use `--channel beta|alpha` for prereleases, `--yes` for non-interactive execution, `--no-wait` to return after queuing, or `--json` for machine-readable output. Review cloud Control Plane trust requests on the node: ```bash sudo task-handoff-node-agent trust list sudo task-handoff-node-agent trust list --verbose sudo task-handoff-node-agent trust list --json ``` The summary uses the node hostname and existing Control Plane pairing names. Unnamed or duplicate names include a short ID. Compare the verification code with the Control Plane before running the printed approval command. `--verbose` includes full fingerprints, IDs, timestamps and revocation commands; `--json` retains the machine-readable trust snapshot. First-time cloud requests without a known pairing name appear as unnamed. An installed Node Agent can also generate a one-time invitation directly on the node: ```sh sudo task-handoff-node-agent invite --ipc-path /run/task-handoff/node-agent.sock ``` Add `--json` for automation-friendly output. Remote TCP access still requires an invitation and paired HMAC authentication. To remove a standalone Node Agent installation: ```sh sudo task-handoff-node-agent uninstall ``` The command removes the systemd service and runtime packages, then asks whether to delete the Node Agent data directory. The default is No. Use `--keep-data` or `--delete-data` for non-interactive execution. Managed Docker volumes are preserved. ## CLI `@task-handoff/server` provides the unified `task-handoff` command: ```sh task-handoff control-plane task-handoff node-agent task-handoff node-agent-invite task-handoff web task-handoff help ``` Use `pnpm cli help` during development. Chat adapters, bindings, AI session messages, queues, and approvals are managed by the control plane. ## Interface Language The control-plane UI supports English (`en-US`) and Simplified Chinese (`zh-CN`). Open **Settings → Appearance → Language** to follow the system language or choose a language explicitly. The interface updates without reloading control-plane data. The preference is stored only in the current browser. Terminal output, logs, AI messages, repository content, and other user- or provider-supplied data are never translated. ## Repository Layout ```text apps/cli/ CLI entry point apps/desktop-shell/ Electron desktop shell apps/mobile/ Expo iOS and Android client packages/control-plane/ Control plane and chat gateway packages/control-plane-client/ Shared Control Plane API and realtime client packages/control-plane-ui/ Control-plane Vue UI packages/controlled-instance/ Controlled-instance HTTP/WebSocket API packages/controlled-instance-ui/ Frozen controlled-instance Vue UI packages/node-agent/ Node Agent runtime and controlled-instance orchestration packages/runtime-shared/ Runtime helpers shared by Control Plane and Node Agent packages/ai-session-runtime/ AI session runtime packages/app-runtime/ Managed application runtime and catalog packages/protocol/ Cross-component protocols and data models packages/core/ Shared capabilities, diagnostics, and storage packages/web-theme/ Web theme and Markdown rendering scripts/ Installation, build, and runtime scripts ``` ## Releases ### Runtime and server packages A semantic version tag such as `v1.2.3` builds the controlled-instance runtime artifacts, publishes `@task-handoff/control-plane`, `@task-handoff/node-agent`, `@task-handoff/controlled-instance`, and `@task-handoff/server`, and attaches the installer and immutable artifacts to the GitHub Release. `alpha` and `beta` versions use their matching npm dist-tags; stable versions update `latest`. ### Docker images The six public base images and their independent `docker-vX.Y.Z` release workflow are maintained in the [TaskHandoff Images repository](https://github.com/edgestorage/task-handoff-images). They contain system dependencies and developer tools, but not the controlled-instance runtime. Node Agent remains the authority for mounting the bootstrap bundle and installing the desired runtime artifact. The Control Plane image market uses the bundled snapshot by default; desktop releases (GitHub Release installers) pin the official catalog verification key (materialized from the `TASK_HANDOFF_MARKET_CATALOG_PUBLIC_KEY` repository variable, falling back to the bundled official key) and pull their catalog from