HAPI: A Local-First Remote Control Layer for AI Coding Agents

The Problem: Your AI Agent Is Stuck at Your Desk

AI coding agents like Claude Code and Codex run in a terminal on your machine. That works fine until you step away. Long builds, test suites, or agent loops need approvals, and you are not there to press enter. HAPI solves this by wrapping the agent process locally and exposing a remote control surface. You start the agent on your workstation, then approve requests, view output, and even run commands from a phone or browser. The target user is a developer who wants the full power of a local agent without being physically present. It is not a cloud IDE and it does not replace the agent. It is a remote control layer that keeps the agent running where you left it.

How HAPI Works: Hub, Relay, and Terminal UI

The core mechanism is a hub process that you start on the machine running the agent. The README shows two commands: `npx @twsxtd/hapi hub --relay` to start the hub with an end-to-end encrypted relay, and `npx @twsxtd/hapi` to run Claude Code. The hub displays a URL and QR code. Scanning the QR code with a phone opens the web app or PWA, which connects back to the hub. The relay uses WireGuard and TLS, so data is encrypted from your device to your machine. The architecture is local-first: the agent runs on your hardware, the hub mediates access, and the relay only carries encrypted traffic when you are remote. The README mentions that `hapi server` remains supported as an alias, which suggests a simpler mode without the relay for local-only use, though details are not given. The workspace browser feature is opt-in via `hapi runner start --workspace-root <path>` flags, letting you browse scoped file trees and start sessions in allowed subdirectories. This is a notable security boundary: you explicitly choose which directories are visible remotely.

Getting Started: Two Commands and a QR Code

Installation is minimal. You need Node.js and npx, or Bun 1.4.0 if you build from source. The README gives two commands to start. First, `npx @twsxtd/hapi hub --relay` launches the hub with the encrypted relay. Second, `npx @twsxtd/hapi` runs Claude Code. The terminal prints a URL and QR code. You scan the QR code with your phone or open the URL to access the control interface. That is the entire setup for the basic case. For self-hosting without the default relay, the README points to Cloudflare Tunnel or Tailscale options in the installation guide, but does not provide those details in the excerpt. Building from source requires Bun 1.4.0 and the commands `bun install` then `bun run build:single-exe`, which produces a single executable. The ease of starting with npx is a strong point: no server setup, no account creation, no cloud deployment. The trade-off is that you are trusting the npx package and the relay infrastructure, though the relay is described as end-to-end encrypted.

Supported Agents and the Unified Workflow

HAPI claims support for a long list of agents: Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, Kimi, Copilot, Antigravity, Pi, and DeepSeek Harness. The README says it wraps your AI agent instead of replacing it, meaning you keep the same terminal experience and muscle memory. The value is a single control surface for many agents. If your team switches between Claude Code and Codex, you do not need to learn a new remote tool for each. The unified workflow is the main selling point, but the README does not detail how the wrapper interacts with each agent's specific permission prompts or output formats. That is a gap. The list is impressive, but you should verify that your exact agent version is supported before relying on it. The documentation links to a supported agents page, which is not included in the excerpt, so the actual compatibility matrix is unknown from this material.

Remote Control Features: Approvals, Terminal, Voice

The feature list includes one-tap approval of AI requests from your phone, running commands from a browser or phone, and a voice assistant for hands-free control. The approval feature is the core use case: you are AFK, the agent asks for permission, you tap approve on your phone. The terminal anywhere feature gives you a shell directly connected to the working machine, which is more powerful and riskier than just approving prompts. The voice assistant is a differentiator; no other remote agent control tool in this space typically offers voice input. The workspace browser is opt-in and scoped, which is a sensible security design. The README does not explain how voice commands are processed or whether they are transcribed locally or sent to a cloud service. That is a privacy question worth investigating before using it with sensitive code. The combination of these features makes HAPI feel like a full remote desktop for your agent, but the security implications of exposing a terminal to a phone are significant. The relay encryption helps, but the attack surface is broader than a simple approval button.

Limitations and When It Is the Wrong Tool

HAPI is not for everyone. If you are on a managed laptop with strict network policies, the WireGuard relay may be blocked or require admin rights to install. The README does not mention any fallback for corporate proxies. If you use a hosted agent like GitHub Copilot in the cloud, HAPI adds nothing because the agent is already remote. The tool is designed for local agents, so if your team standardizes on cloud IDEs, it is the wrong fit. The AGPL-3.0 license is a real constraint for companies that want to embed or modify the tool without open-sourcing their changes. That is a legal consideration, not a technical one, but it can be a dealbreaker. The README also notes that native iOS and Android apps are in development, so the mobile experience currently relies on the PWA and Telegram Mini App. The PWA may have limitations with background notifications or camera-based QR scanning, though the README does not specify. Finally, the project is moving fast: releases v0.29.0, v0.28.0, and v0.27.3 all landed within a week, which means the API and behavior can change quickly. That is a maintenance cost to plan for.

Alternatives: Happy and Self-Hosted Tunnels

The README explicitly positions HAPI as a local-first alternative to Happy, which is the original project. Happy is the predecessor, and HAPI credits it as the inspiration. The key difference is local-first versus hosted. Happy likely runs as a hosted service, while HAPI keeps everything on your machine and uses a relay only for encrypted transport. If you want a fully managed solution with no infrastructure to maintain, Happy may be simpler. If you want control over your data and the ability to run offline, HAPI is the better fit. Another alternative is to skip the relay entirely and use a generic tunnel like Cloudflare Tunnel or Tailscale, which the README mentions for self-hosting. That approach gives you the same remote access but without HAPI's approval UI, voice assistant, or unified agent support. You would need to build your own control layer on top of the raw tunnel. The trade-off is between a purpose-built tool with a polished UI and a generic network solution that requires more assembly but gives you full control.

Maintenance and Upgrade Considerations

The release cadence is high: three releases in seven days, from v0.27.3 to v0.29.0. That suggests active development and rapid iteration, but it also means breaking changes are possible between releases. The README does not mention a migration guide or a stable API promise. You should pin the version you use and test upgrades in a staging environment before applying them. The build process with Bun is straightforward, but the `build:single-exe` target may produce platform-specific binaries, so you need to rebuild for each OS you support. The license is AGPL-3.0, which requires you to provide source code for any modifications you distribute or offer as a network service. If you are using HAPI internally without modification, that is not an issue, but if you plan to fork or extend it, be aware of the copyleft obligations. The native apps are in development, so the mobile experience will change; if you rely on the PWA, monitor the release notes for changes to the client contract.

Editorial conclusion

Adopt HAPI if you live inside a terminal-based AI agent and need to approve long-running tasks from your phone, or if you want a unified workflow across Claude Code, Codex, Cursor Agent, and others. Skip it if you prefer a fully hosted solution, if your agent is not on the supported list, or if you cannot accept the AGPL-3.0 license for your use case. Before adopting, verify that your specific agent version works with the current release, test the relay under your network conditions, and decide whether the WireGuard + TLS relay meets your security requirements.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes