tesseract-agent

Run your tesseract agents on a remote machine. Install this on a headless Linux/macOS/Windows box (or in Docker) to make that machine available to your tesseract account — your laptop, phone, or the web app can then run agents on it, even with no GUI and even when nothing else is open.

It's the headless counterpart to the desktop app's "share this machine" hosting: the same agent runtime, no Electron.

Install

npm i -g tesseract-agent

Requires Node 20+. Hosting is a paid-plan feature — a Free account is denied and the daemon backs off gracefully.

Use

tesseract-agent login            # browser sign-in (Google/email) → paste a one-time code
tesseract-agent install          # run as a background service (launchd/systemd/Task Scheduler)
tesseract-agent status           # is it running / connected?
tesseract-agent logs             # tail the service logs
tesseract-agent logout           # revoke this device + wipe local state

login prints a URL (and a scannable QR) to https://app.tesseract.dev/?authorize=…; sign in there, then paste the one-time code back in the terminal. For automation, --token <device-JWT> skips the browser. --api / --relay point at a self-hosted backend (default https://app.tesseract.dev).

The service auto-starts at login/boot and restarts on crash: launchd LaunchAgent on macOS, systemd --user unit on Linux (with loginctl enable-linger so it survives logout), Task Scheduler ONLOGON task on Windows. Run install as your normal user — not sudo (a per-user service needs your own session, and finds your credentials + ~/.claude).

Multiple agents under one user

By default there's one agent per OS user. To run a separate agent under the same user, give it an instance id — it gets its own state dir, device, and service:

tesseract-agent login   --instance work2
tesseract-agent install --instance work2
tesseract-agent status  --instance work2

install warns and asks for confirmation if a daemon is already running for the target instance (pass --yes to skip the prompt in scripts). Different OS users are always isolated — no instance id needed.

Docker / no init system

A container has no launchd/systemd, so skip install and run the daemon as the entrypoint:

docker run --rm \
  -e TESSERACT_TOKEN \
  tesseract-agent \
  sh -c 'tesseract-agent login --token "$TESSERACT_TOKEN" && tesseract-agent run'

Or pre-provision credentials and mount them (persist ~/.tesseract or set CCB_DAEMON_DIR to a mounted volume), then just tesseract-agent run.

The agent runs under the machine's own Claude credentials — a claude login in ~/.claude, or an ANTHROPIC_API_KEY in the environment.