Skip to main content

Self-Hosting & Remote Access

You work with Helix on the office network all day, then want to continue in the same workspace from home. Or your code can only live on company servers and must never touch a third party. Or you have three machines that should talk to each other like one LAN.

Helix's answer is not "move everything to the cloud" — it's three complementary connection modes that keep Agents running on your own infrastructure, with the connection adapting to the scenario:

  • Direct connection — on the same LAN, the client connects to the Agent directly
  • Self-hosted tunnel — traverse NAT through your own gateway, reach an internal Agent from any network
  • VPN networking — join multiple devices into one virtual LAN, as if they were under the same router

Why Self-Host​

For many teams, sending code and prompts to a third-party cloud is a non-starter. The core value of self-hosting:

  • Data sovereignty — session history, codebases, and tool outputs stay on your own machines; nothing passes through third-party storage
  • Private network access — Agents run inside your network but remain reachable from anywhere
  • Compliance & governance — meet data-residency, audit, and access-control requirements
  • Cost control — reuse existing server capacity instead of paying per seat or per usage

Helix's desktop, backend, and web clients can all point at your own Agent instances. Combined with the connectivity features below, that's a complete self-hosted stack.

Self-Hosted Tunnel: A Secure Channel Through NAT​

Home and office machines usually have no public IP. Instead of asking you to reconfigure routers or set up port forwarding, Helix provides a self-hosted gateway (EasyGateway) that runs on your server and establishes an encrypted channel.

How It Works​

┌────────────┐   Encrypted   ┌──────────────────┐   Reverse proxy   ┌──────────────┐
│ Your device │ ◄──────────► │ EasyGateway      │ ◄───────────────► │ Internal Agent │
│ (any network)│   mTLS/session│ (your server)   │   subdomain route │ (home/office) │
└────────────┘                └──────────────────┘                    └──────────────┘
  1. Node registration — an internal Helix Agent connects to your gateway as a node, completes identity registration and credential issuance
  2. Subdomain assignment — the gateway assigns each node a dedicated subdomain, e.g. mybox.gw.example.com
  3. Client access — you reach that subdomain from any network; the gateway securely forwards traffic to the internal Agent
  4. Live monitoring — the gateway shows each node's connection status and real-time traffic speed

Key Design Choices​

  • Mutual TLS (mTLS) — nodes request client certificates via CSR; only verified nodes can join. All transport is encrypted
  • Heartbeat & auto-reconnect — the control channel has heartbeat detection; connections recover automatically after network jitter, and silently dead channels are detected and re-established
  • Session credentials — nodes authenticate with session tokens that can be rotated; revoking a token disables the node immediately
  • Registration-free deployment — the gateway supports a self-contained mode that runs with a single config file and no external dependencies — suitable for fully offline internal networks
  • User mapping (optional) — the gateway can integrate with your user system to show which user owns each node, for easier auditing

Typical Scenarios​

  • Remote work — run Agents on office servers, keep working from home with identical workspaces, sessions, and toolchains
  • Exposing internal services — temporarily show an internal web service to an external colleague without touching the firewall
  • Team sharing — a team shares one self-hosted Agent, each member connects from their own client

VPN Networking: Many Machines, One Virtual LAN​

Tunnels solve "reach a single Agent." When you have multiple machines that need to reach each other (this box connects to that box's database, that box calls this box's API), Helix also offers TUN-based VPN networking.

How It Works​

Helix's VPN client creates a virtual network interface (TUN device) on each machine — macOS uses the system utun, Linux uses native TUN — and joins a virtual LAN maintained by the gateway:

  • CIDR route table — each device registers its local subnets (e.g. 192.168.1.0/24) in the route table; other devices forward packets using longest-prefix matching
  • Pure userspace implementation — packet forwarding happens entirely in user space; no admin-level system route configuration needed (no CGO dependency on macOS/Linux)
  • Auto-reconnect — connections recover automatically after network switches (Wi-Fi → hotspot) without interrupting work

Three Modes​

ModePurpose
tunnelAccess specific services through the gateway — ideal for exposing a single port on demand
proxyAccess via gateway proxying — ideal when you need a unified egress point
vpnFull networking with direct inter-device connectivity — ideal for multi-machine coordination

Typical Scenarios​

  • Local dev against a test DB — a laptop's Helix reaches an office database directly, as if on the same LAN
  • Multi-machine coordination — one machine runs models, one runs builds, one runs tests; Agents orchestrate them over VPN
  • Cross-region teams — member devices join one virtual LAN and share internal resources

There's no longer just one path. Helix maintains both direct and tunnel links and continuously probes latency:

  • Same LAN → automatically uses the direct link for lowest latency
  • Cross-network → automatically switches to or parallel-uses the tunnel
  • Link quality changes → re-selects the optimal path automatically, no manual switching

The practical effect: whether you're in the office or at home, Helix "invisibly" uses the fastest available path.

Synergies with Other Capabilities​

With Workspaces​

Each Workspace can bind to Agents in different locations — local, remote server, or machines inside your VPN. Session history, tool configuration, and model selection stay fully independent; switching Workspace switches the connection target.

With Multi-Machine Management​

On top of self-hosting + VPN, Helix's machine management gives you a machine-centric view of all Agent connections: online/offline status and project distribution at a glance.

With HelixVM​

HelixVM creates isolated environments on the local machine; self-hosting/VPN extends Agents to other machines. Together they form a complete "local sandbox + remote execution" matrix.

With the Security Model​

Helix's API is protected by long-lived credentials plus a pairing flow, and self-hosting uses the same model: after first-time pairing, credentials are issued and every request carries identity verification. Combined with gateway mTLS, that's a three-layer defense: transport encryption + node authentication + user authorization.

Quick Start​

  1. Deploy the EasyGateway on your server (single binary, one command to start)
  2. Install Helix Agent on the machines you want to reach; configure the gateway address and complete node registration
  3. Add the corresponding Workspace in your Helix client and choose the connection mode (direct / tunnel / VPN)
  4. Verify connectivity — the client automatically measures latency and picks the optimal link

For detailed deployment steps and configuration options, see the API & Configuration documentation.