TaskHandoff Logo

TaskHandoff

A free, open-source, self-hostable control plane for AI remote work and server operations

Node.js 24.15+ Vue 3 TypeScript 6 Docker Ready Apache-2.0 License

English | 简体中文

--- TaskHandoff is a free, open-source, self-hostable control plane for AI remote work and server operations. It brings Codex and OpenCode development work into one control plane, connecting AI sessions spread across machines, workspaces, and chat platforms while managing node enrollment, instance lifecycles, sessions, applications, and message routing. > **Beta:** TaskHandoff is under active development. Breaking changes may land between releases. ## Use Cases - **Many machines, one control plane** — Connect multiple workstations or servers and let agents work in isolated instances without switching between separate environments. - **Code and operate servers from anywhere** — Use Desktop or a browser for full development and server-management workflows, and Mobile or chat for monitoring, approvals, and remote controls. - **Run agents in containers** — Give each agent its own Docker-backed isolated instance today. Kubernetes runtime support is still under development. ## Product Focus TaskHandoff is being developed around three directions: - **One entry point** for every connected device, workspace, and AI session; - **multi-terminal access** across Desktop, browser, Mobile, and chat for remote collaboration; - **server management for large-scale environments**, with lifecycle and operational visibility centralized in one Control Plane. ## Current Scope - **Agent kernels:** Codex and OpenCode only. Claude may remain visible as a compatibility path in existing images or configurations, but it is not a first-class supported kernel. - **Remote Desktop:** window-level capture is supported, along with an entire desktop, a single application, or a custom region. Session previews are read-only; open the full viewer to control input. - **Instances:** Docker container instances are supported today. A built-in Local Runtime is also available; Kubernetes runtime support is still in development and is not yet a supported deployment target. ## Interface ### Workbench ![TaskHandoff workbench](https://raw.githubusercontent.com/edgestorage/task-handoff-docs/main/docs/public/images/workbench-dark-en.png) ### Story Light mode: ![TaskHandoff Story workspace in light mode](https://raw.githubusercontent.com/edgestorage/task-handoff-docs/main/docs/public/images/story-workspace-light-en.png) Dark mode, with a Story session and a browser running in the container: ![TaskHandoff Story workspace in dark mode](https://raw.githubusercontent.com/edgestorage/task-handoff-docs/main/docs/public/images/story-workspace-dark-en.png) ### Mobile

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 out of the box, while other deployments enable remote loading once a verification key is configured. Both degrade through remote, local cache, then the bundled snapshot; the cache lives at `market/catalog-cache.json` inside the data directory. The issued catalog is authoritative for the repositories it references: remote responses must pass schema validation and mandatory ed25519 verification, and remote loading stays disabled while no public key is configured. Configuration: - `TASK_HANDOFF_MARKET_CATALOG_URL` overrides the catalog URL (official URL by default); set it to `off`/`0` to disable remote loading. - `TASK_HANDOFF_MARKET_REFRESH_INTERVAL` sets the refresh interval in seconds (six hours by default); `0` keeps manual refresh only. - `TASK_HANDOFF_MARKET_CATALOG_PUBLIC_KEY` is required to enable remote loading: the ed25519 key (PEM or base64 SPKI). Desktop releases ship the official key by default; the GitHub repository variable configures the packaged default and the process environment overrides it at runtime. `TASK_HANDOFF_MARKET_CATALOG_KEY_ID` optionally pins the key identifier carried by the catalog signature. - `TASK_HANDOFF_MARKET_ALLOWED_REPOSITORIES` is an optional comma-separated repository allowlist (matched on repository path boundaries) for deployments that want to restrict the catalog to their own registry. ### Desktop application Semantic version tags build macOS arm64/x64, Windows arm64/x64, and Linux x64 installers and publish them to GitHub Releases. Versions with an `alpha` or `beta` suffix are marked as prereleases. macOS artifacts are signed, notarized, stapled, and verified with Gatekeeper. Windows code signing is not enabled yet. Closing the Desktop control-panel window keeps TaskHandoff running in the system tray. The tray shows the current Control Plane and Node Agent service status and can reopen the existing window without restarting either service. Choose **Quit TaskHandoff** from the tray or the platform application menu to stop the Desktop services. A graceful Node Agent shutdown stops Local Runtime controlled instances so they can be restored on the next launch; Docker Runtime controlled instances keep running and are rediscovered when the Node Agent returns. ### Mobile application A stable tag in the exact form `mobile-vX.Y.Z` runs the mobile release checks and starts independent Android and iOS release jobs. GitHub-hosted Linux and macOS runners build and sign both native applications. Android attaches an APK to the corresponding GitHub Release, which is never marked as Latest; after approval through the `ios-production` environment, iOS uploads directly to App Store Connect/TestFlight. Final App Store review remains a manual action, and Android is not submitted to Google Play by this workflow. See [`apps/mobile/README.md`](apps/mobile/README.md) for the client boundary and development commands, and [`apps/mobile/RELEASE.md`](apps/mobile/RELEASE.md) for credentials, first-build setup, and release operations. ## License TaskHandoff is licensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution information.