Headless mode

Headless mode runs hob without a native desktop window. The hob process stays on a VM, workstation, or server, and you connect to it from a browser.

This is for developers who want agents running somewhere other than a local laptop:

• Security isolation — keep agent CLIs, repository credentials, shell commands, and generated changes inside a dedicated VM instead of your personal machine.
• Uptime — let long-running agents, tests, terminals, and workflows continue when your laptop sleeps, disconnects, or moves networks.
• Centralized setup — install agent CLIs, MCP servers, SDKs, language toolchains, and project dependencies once on a stable host.
• Remote review — use the full IDE from a browser, and use hob roam from a phone or tablet to monitor agents, approve requests, or send follow-up instructions.

Headless mode is not a reduced dashboard. It serves the same hob IDE surface you get in the desktop app: workspaces, tiled agent panes, terminals, render panes, workflows, activity, artifacts, issues, settings, source control, and the same agent backend configuration. hob roam works with headless too, including the internet relay when enabled.

Start hob on a VM

Install hob on the VM or server:

curl -fsSL https://get.hob.dev/install | sh

Activate your license from a shell:

hob app license activate

For non-interactive setup:

printf '%s\n' "$HOB_LICENSE_KEY" | hob app license activate --key-stdin

Install and authenticate the agent CLIs you plan to use on that same host, such as Claude Code, Codex, or OpenCode. Agents run where the headless hob process runs, so their config, tokens, MCP servers, shell environment, and filesystem access should be configured on the VM.

Start hob from the project you want to work in:

cd /srv/my-project
hob --headless

You can also pass the project directory:

hob --headless /srv/my-project

On startup, hob prints a Browser UI: URL. Open that URL in a browser to enter the full IDE. The URL includes a credential fragment; treat it like a secret and regenerate credentials from the Remote popup if it is exposed.

Connect securely

The default headless setup is designed for SSH tunnels. Headless mode forces Remote IDE to at least Local host, so you can connect without opening a public VM port:

ssh -L 22907:127.0.0.1:22907 [email protected]

Then open the Browser UI: URL locally, replacing the host with 127.0.0.1 if needed. hob uses HTTPS for headless by default, so your browser may ask you to accept the local certificate the first time.

For a trusted LAN or VPN, set Settings → Remote → Remote IDE access to Local network. Headless uses 0.0.0.0:22907 by default, so the server listens on all interfaces unless you change Settings → Remote → Server listen address in Advanced mode. Open TCP port 22907 only on networks you trust.

Remote IDE does not have a public internet mode. For full IDE access across the public internet, use SSH forwarding, a VPN, or another private tunnel. hob roam is the mobile companion that can use hob's relay.

Use it like desktop hob

After you connect, the workflow is the same as desktop:

1. Open one or more agent panes.
2. Tile terminals and render panes next to them.
3. Let agents run on the VM while you review plans, approve commands, inspect diffs, and commit finished work.
4. Close your browser when you are done; the headless process and active sessions keep running.
5. Reopen the browser URL later to return to the same workspace context.

Because agents execute on the VM, make sure the VM has the repository, branch state, credentials, toolchains, package caches, and environment variables the agents need. Treat it like the machine doing the development work, not just a display server.

Add hob roam

hob roam is available from headless mode for phone and tablet access. Set Settings → Remote → Roam app access to Local host, Local network, or Internet.

Use roam when you do not need the whole IDE but still want to keep agents moving:

• watch agent conversations and tool calls
• approve or deny permission requests
• send messages to running agents
• stop agents
• inspect terminal output

For a full-time VM, Roam: credentials mode set to Fixed plus Roam: auto-enable on startup gives you a stable, bookmarkable mobile entry point that comes back after restarts.

Run it full time

For a long-lived VM, run hob under your normal process supervisor after the first interactive setup. For example, a systemd user service can keep a project-hosted headless instance running:

[Unit]
Description=hob headless
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/srv/my-project
ExecStart=/usr/local/bin/hob --headless /srv/my-project
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Use one headless process per project directory you want to keep live. Each process owns its workspace state, terminals, agent sessions, and browser URL for that project.

Security checklist

• Run headless hob as a dedicated user when possible.
• Keep Remote IDE on Local host unless you are on a trusted LAN or VPN.
• Prefer SSH forwarding, a VPN, or another private tunnel for full IDE access.
• Use roam internet access only when you want the mobile companion reachable through connect.hob.dev.
• Rotate Remote IDE or roam credentials from the Remote popup if a URL was shared too broadly.
• Keep repository, package-manager, cloud, and model-provider credentials scoped to what agents actually need on the VM.

Related