Remote Access

Holon supports running as a remote daemon and connecting from a TUI or API client on another machine. This is the foundation for team-shared agents, headless deployment, and remote development workflows.

Access Modes

Both holon daemon start and holon serve accept an --access flag:

Mode	Description	Use Case
`local`	Loopback only (127.0.0.1)	Default; single-machine use
`lan`	Local network	Same LAN, known IP
`tunnel`	Cloudflare Tunnel	Public access through a tunnel
`tailnet`	Tailscale network	Private mesh between your devices

Remote Server

Tunnel Mode (Cloudflare)

Start a daemon accessible through a Cloudflare Tunnel:

holon daemon start --access tunnel

Or use the standalone server:

holon serve --access tunnel

The runtime manages the tunnel lifecycle. No Cloudflare configuration is required on your side — Holon creates and manages ephemeral tunnels automatically.

Tailnet Mode (Tailscale)

For private mesh access between your own devices:

holon daemon start --access tailnet
holon serve --access tailnet

Requires Tailscale to be installed and authenticated on the host machine.

LAN Mode

For same-network access with a known IP:

holon serve --access lan --host 192.168.1.10 --port 8787

Custom Host and Port

Override the default listen address:

holon daemon start --access tunnel --port 9000
holon serve --access lan --host 0.0.0.0 --port 8787

Connecting Remotely

TUI Connection

Connect from a remote terminal:

holon tui --connect https://your-server:8787 --token "your-token"

Read the token from a file:

holon tui --connect https://your-server:8787 --token-file ~/.holon/remote.token

Use a stored token profile:

holon tui --connect https://your-server:8787 --token-profile my-profile

HTTP API

The same token authenticates HTTP control plane requests:

curl -H "Authorization: Bearer your-token" \
  https://your-server:8787/v1/agents/list

See the HTTP Control Plane reference for the full API surface.

Token Management

Generating a Token

Tokens are generated when the server starts. Capture the token from the startup output or create a dedicated file:

# On the server, save the token
holon daemon start --access tunnel --token-file ~/.holon/remote.token

Token Profiles

Store multiple tokens as named profiles in your configuration:

holon config set tokens.office "token-for-office-server"
holon config set tokens.home "token-for-home-server"

Then connect by profile name:

holon tui --connect https://office:8787 --token-profile office
holon tui --connect https://home:8787 --token-profile home

Daemon Management

Once the daemon is running, standard management commands work remotely:

holon daemon status
holon daemon logs
holon daemon restart
holon daemon stop

Security Considerations

Always use a token. Remote connections without a token are rejected for non-local access modes.
Prefer tunnel or tailnet over LAN mode when connecting across the internet. These provide encryption and authentication without exposing raw ports.
Rotate tokens by restarting the daemon with a new --token-file.
Use --access local when only local connections are needed. This is the default and the most secure option.
The HTTP control plane applies trust-boundary rules: read-only routes (agent state, events, tasks) still require a valid token for remote access.