Connect to a remote Holon runtime

Run Holon on one machine and use it from another — a shared team server, a headless box, or a remote dev host. This guide picks an access mode, connects, and confirms the connection works.

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/api/agents/list

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

Token Management

Providing a Token

Holon does not generate control tokens for you. Pick a secret yourself, then hand it to the server with --token, --token-file, or the HOLON_CONTROL_TOKEN environment variable:

# Read the control token from a file
holon daemon start --access tunnel --token-file ~/.holon/remote.token

Token Profiles

Store multiple tokens as named credential profiles, then select one by name:

holon config credentials set office --kind bearer_token --stdin
holon config credentials set home --kind bearer_token --stdin

Then connect by profile name:

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

Mobile Access via Android Client

You can also connect to remote runtimes from an Android phone or tablet using the native Holon Android client. Provide your remote HTTPS base URL and token to start an encrypted mobile session. See Connect with the Android client.

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. Holon refuses to start with a non-loopback listen address, or with --access lan/--access tailnet, unless a token is set. Set a token for --access tunnel too: the tunnel is publicly reachable.
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.
Team deployments: For shared multi-user deployments, switch to OIDC authentication (auth.mode = "oidc"). This replaces the shared control token with individual SSO logins. See Configure OIDC authentication.