Quick Start

Install Longhouse, open it, and find one of your own sessions. That is the first proof it is already useful on this machine.

0. Get a Longhouse address

Connecting a machine needs a Longhouse to connect to. A hosted one is invite-only for now; to run your own on this machine (Linux or macOS):

curl -LsSf https://astral.sh/uv/install.sh | sh   # skip if you have uv
uv tool install longhouse
longhouse-server onboard

That starts a Runtime Host at http://127.0.0.1:8080, installs the Machine Agent, and asks what history to import, so you can skip to step 4. It stops when the machine does; to keep one running, see Configuration.

Your own always-on box, over Tailscale

If the box and your laptop share a tailnet, you do not need a domain or https. Tailscale already encrypts the link, so native clients accept plain http:// to a Tailscale address (100.x.y.z, an fd7a:115c:a1e0:: address, or a *.ts.net name). Start the Runtime Host on the box; it prints a Tailscale: address:

longhouse-server serve --host 0.0.0.0

longhouse auth --url http://100.x.y.z:8080     # or http://my-box.your-tailnet.ts.net:8080
longhouse machine repair --repair-service

The macOS app and the iPhone app follow the same rule. A plain LAN address (192.168.x, 10.x, 172.16-31.x, *.local) is refused unless you opt in with --allow-insecure-http (or LONGHOUSE_ALLOW_INSECURE_HTTP=1; in the iPhone app, the switch in the server settings). The choice is remembered with the address and every use warns, because the device token and every transcript then cross that network unencrypted. Any other address needs https://.

1. Connect a machine

Run this on the machine where you use Claude Code, Codex, or another coding agent (macOS, Linux, or WSL), with your Longhouse address in place of the example. An empty timeline shows this line with its own address filled in.

curl -fsSL https://get.longhouse.ai/install.sh | LONGHOUSE_URL=https://you.longhouse.ai bash

It installs Longhouse (on a Mac, also Longhouse.app), opens your Longhouse in the browser to approve the machine, and starts its Machine Agent. No Python runtime and no sudo needed.

No browser on that machine, such as a server over SSH? In Settings → Devices, create a token; the page gives you one line that connects the server without a browser.

2. Finish later

If you skipped the approval or installed without an address, open Longhouse.app on a Mac and choose Sign in to connect this Mac. Anywhere else:

longhouse auth --url https://you.longhouse.ai
longhouse machine repair --repair-service

This laptop setup is the fast proof path. When you want Longhouse to stay reachable while the laptop sleeps, move the Runtime Host to a machine that stays on and keep the Machine Agent on the dev machine where work happens.

3. Choose what history to import

Setup asks what to do with sessions your agents already saved on this computer. Old transcripts can hold code and secrets from any project you ever ran an agent in, so the default imports nothing old: only sessions you start from now on. Import history when you want it, for one project or for everything:

longhouse machine scope                        # what is imported, what is left out
longhouse machine scope --project ~/git/app    # add one project's full history
longhouse machine scope --since all            # import everything on this computer

Changing the scope backfills what became eligible; nothing older than your choice is uploaded until then. To remove Longhouse from a computer (and revoke its token), run longhouse uninstall.

4. Find a session

Start a session in Claude Code, Codex, Cursor Agent, OpenCode, Pi, Oh My Pi, or Antigravity, then look for it in the timeline or search. A session you start after setup appears within seconds.

5. Launch a managed session

Bare provider CLIs are useful for compatibility import, but they are not the default path once Longhouse is installed. Start through Longhouse when you want a managed session to stay reachable later:

longhouse claude       # Claude Code
longhouse codex        # Codex CLI
longhouse cursor       # Cursor Agent
longhouse opencode     # OpenCode
longhouse pi           # Pi Agent
longhouse omp          # Oh My Pi
longhouse antigravity  # Antigravity CLI, send only

When Longhouse launches the session, it owns the session record and local observation path. All seven providers ship today; what they can do after launch differs. Every provider but Antigravity can be steered mid-turn. OpenCode Helm supports managed send, interrupt, terminate, pause-answer, and active-turn steer that lands at the next step boundary. Antigravity takes send alone, and refuses to start if its Longhouse hook is not installed. The Integrations page carries the full provider detail, generated from the managed-provider declarations.

6. Troubleshooting

Most people should not need this on the first run. If the timeline or menu bar says something is wrong:

longhouse local-health --json
longhouse machine repair
longhouse machine repair --repair-service

On macOS, Longhouse.app and the menu bar show the same local health information in ambient form.