Skip to content

getting-started.md

Latest commit

 

History

History
126 lines (85 loc) · 4.06 KB

getting-started.md

File metadata and controls

126 lines (85 loc) · 4.06 KB
Raw

Getting started

This guide takes a clean machine from zero to its first persistent RoamCode Session. RoamCode supports macOS and Linux directly; Windows uses WSL2.

What gets installed

roamcode install creates a per-user service:

  • macOS: a LaunchAgent named com.roamcode
  • Linux: a systemd --user service named roamcode

The service listens on 127.0.0.1:4280 by default. Program versions live under ~/.local/share/roamcode; operational data lives under ~/.config/roamcode. Existing pre-rename installations continue to use their compatible legacy data path when detected.

1. Prepare the tools you want

Install Claude Code, Codex, or another supported adapter on the machine that will run the work. Complete that provider's normal authentication flow before running it. RoamCode uses the existing CLI login; it does not collect a provider API key.

This step is optional for opening a Session: every manual Session starts as an ordinary shell. You can install multiple agents and choose one simply by running its command in the terminal.

2. Install RoamCode

macOS: Homebrew (recommended)

The formula brings Node.js and tmux with it:

brew install burakgon/roamcode/roamcode
roamcode install

macOS or Linux: published CLI

Requirements:

  • Node.js 24 or newer
  • tmux
  • npx, included with Node.js

On Ubuntu or Debian, install tmux with:

sudo apt-get update && sudo apt-get install -y tmux

Then run the small bootstrap:

curl -fsSL https://roamcode.ai/install | bash

The bootstrap only checks prerequisites and delegates the durable installation to the latest stable roamcode npm package. To inspect before executing, open scripts/install.sh, or run the same published CLI directly:

npx --yes --allow-scripts=better-sqlite3,node-pty roamcode@latest install

Do not use sudo for the RoamCode install. The service and its data belong to your user.

3. Pair the first browser

After installation, RoamCode waits for the service health check and prints a QR code plus a five-minute, one-use pairing link. Open the loopback link in a browser on the same machine.

You can issue a fresh link at any time:

roamcode pair

The browser receives its own revocable device credential. The host recovery credential is never placed in the URL or browser storage.

4. Start the first Session

  1. Open Sessions and choose New terminal.
  2. Pick a working directory on the Node.
  3. Choose Open terminal.
  4. At the shell prompt, run claude, codex, or another command.

The shell and any agent you start now run inside tmux. You can close the browser, reopen RoamCode, and reattach to the same process. Exiting an agent returns to the shell; exiting the shell ends the Session.

5. Verify the installation

roamcode status
curl -fsS http://127.0.0.1:4280/health

A healthy install reports the service manager and Server: running at http://127.0.0.1:4280.

If an agent command is not available, inspect Agents, /diag, and /providers. The terminal can be healthy while an individual provider executable or login is not. RoamCode never opens an agent sign-in flow merely because a terminal was created.

Connect another device

A 127.0.0.1 link only opens on the Node itself. For a phone or another computer, create a private or HTTPS route you control, then issue the pairing link for that exact stable origin:

roamcode pair --url https://your-roamcode.example

Continue with the remote-access guide. Never expose the plain HTTP port directly to the public internet.

Useful commands

roamcode status       # installed service and loopback reachability
roamcode pair         # new one-use browser pairing link
roamcode --help       # server, API, recovery, and configuration commands
roamcode uninstall    # print safe service-removal commands

For environment variables and non-default data paths, see configuration. For a failed install or an unreachable service, use troubleshooting.