# 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

```bash
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

```bash
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:

```bash
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:

```bash
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.