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 automations 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, automations, 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:

hob --headless

This command runs hob in the foreground. It does not daemonize itself: closing the terminal, ending the SSH session, or pressing Ctrl+C stops the headless server. Closing the browser is different — the browser is only a client, so agents and terminals keep running as long as the hob process is still running.

With no project path, hob restores the last saved project state when one exists. Otherwise it opens in no-project mode, just like desktop hob, so you can choose a project from the browser.

You can still pass an initial project directory when you want to open a specific project:

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. The directory you launch hob --headless from is not treated as a project unless you pass it explicitly.

If you run hob --headless again while the same headless server is already reachable, hob prints the existing Browser UI: URL and exits instead of starting a second server. If the second command includes a project, file, or hob:// link, hob does not open it automatically; open it from the existing browser IDE using the printed URL. This keeps server commands explicit and avoids hidden state changes in a long-running VM session.

Choose how to keep it running

The foreground command is useful while watching startup output, but an ordinary terminal is not a process supervisor. Choose an option based on how long hob should be available:

Use a terminal multiplexer

If you already use tmux, byobu, or screen, you can run hob --headless inside a session and detach as usual. The multiplexer keeps hob running across SSH disconnects and lets you return to its output later. It does not bring hob back after the machine reboots; use systemd for that.

Try a one-off detached run

For a quick background run without managing a terminal multiplexer:

hob --headless --detach

--detach starts hob in a new OS session with its terminal streams disconnected. The command waits for the browser IDE to become reachable, prints its background process ID and Browser UI: URL, and then returns to the shell. Project paths and the other headless flags work the same way:

hob --headless --detach /srv/my-project

Because the detached process has no attached terminal, use this for trying headless mode and other one-off runs rather than as a replacement for service management. On Linux and macOS, stop it gracefully with kill <pid> using the PID printed at startup.

--detach also works for the desktop app: hob --detach [path] launches the window detached from the terminal that started it, prints the background process ID, and returns to the shell — useful when opening hob from a terminal you are about to close. If a running window already has that project open, hob routes the open there and reports it instead of starting a new window.

Run an always-available systemd service

For a long-lived Linux host, let systemd own the foreground process. Use the same Unix account that owns the hob license, settings, projects, and agent CLI credentials. First check where hob is installed:

command -v hob

Create the service file:

mkdir -p ~/.config/systemd/user
${EDITOR:-vi} ~/.config/systemd/user/hob-headless.service

The installer normally puts hob at ~/.local/bin/hob; if command -v hob printed a different path, use that absolute path in ExecStart instead:

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

[Service]
Type=simple
ExecStart=%h/.local/bin/hob --headless
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Do not add --detach: systemd needs the foreground process so it can track, stop, and restart hob. With no project in ExecStart, hob restores its last saved project state or opens the no-project launcher. Add a path after --headless if this service should start with a specific project. Enable and start the service:

systemctl --user daemon-reload
systemctl --user enable --now hob-headless.service
systemctl --user status hob-headless.service

Enable lingering so the user service starts during boot and continues when that user is not logged in:

sudo loginctl enable-linger "$USER"

This last command may require an administrator. Without lingering, a user service normally starts only after that user's first login. View startup output and follow logs with:

journalctl --user -u hob-headless.service -f

You can also run hob --headless from another shell as the same user; it detects the running server, prints the existing Browser UI: URL, and exits. Manage the service with:

systemctl --user restart hob-headless
systemctl --user stop hob-headless
systemctl --user start hob-headless

systemd does not run an interactive login shell. If agent CLIs or toolchains depend on environment variables or a custom PATH, define them in the unit (or an EnvironmentFile) instead of relying on shell startup files. After changing the unit, run systemctl --user daemon-reload and restart the service.

Restrict file references to project roots

By default, an explicit file reference such as @/absolute/path or @~/path can discover and read a file outside the active project. This is useful when you deliberately point hob at a spec, log, or other local context, but some managed installations need every hob file-reference surface confined to trusted projects.

Set HOB_ALLOW_READS_OUTSIDE_PROJECT_ROOTS=false in the environment that starts hob:

HOB_ALLOW_READS_OUTSIDE_PROJECT_ROOTS=false hob --headless /srv/trusted-project

For the systemd unit above, add this line under [Service]:

Environment=HOB_ALLOW_READS_OUTSIDE_PROJECT_ROOTS=false

When disabled, explicit file mentions, file browsing, rendering, and direct file reads remain available inside the active project or worktree, including protection against symlinks that escape that root. Attempts to reach elsewhere return a policy-specific error instead of revealing whether the external path exists.

The variable defaults to true. Only an unset variable gets that default; an empty or invalid value prevents the hob Host from starting. The elected Host keeps the environment it started with, and restart helpers inherit it, so the setting survives ordinary hob relaunches. To change it, stop the running Host and start it again from the new environment. Starting another hob command while the existing Host is still running does not change the active Host's policy.

This setting governs hob's own file-reference and rendering surfaces. Agent subprocess filesystem access is controlled separately by the backend's permission and sandbox settings.

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 -o ExitOnForwardFailure=yes -L 22908:127.0.0.1:22907 [email protected]

The left port (22908) is the port on your local computer; the right port (22907) is the headless hob port on the VM. Choose an open local port that is different from the port configured in hob desktop (22907 by default), even if desktop is not currently running. If desktop owns the port first, the tunnel cannot start; if the tunnel owns it first, a later desktop launch can detect a different headless instance on its configured port and ask you to move the tunnel. ExitOnForwardFailure makes SSH stop immediately instead of leaving you with a session whose tunnel failed to start.

Then open the Browser UI: URL locally, changing its host and port to 127.0.0.1:22908 while keeping the rest of the URL, including its credential. 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 Private networks. 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 process 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. Switch projects from the project chip, project switcher, or Open folder without restarting the headless process.
5. Close your browser when you are done; the headless process and active sessions keep running.
6. 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, Private networks, 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.

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