Skip to main content
Early pricing is live. Start free for up to 3 AI systems — no card, no time limit.Early pricing is live. Free for up to 3 AI systems.
All docs
Tutorial

Install and run the collector

Put the oabo-collector on one machine, send its first report, and check that the feed landed.

15 minFor: Engineer, Workspace owner

Before you start

The collector is a small Python command, oabo-collector, that reads the session logs Claude Code and Hermes already keep on a machine and sends token counts to your workspace. It never reads or sends conversation content. What it sends is in What leaves your machine.

  • Time: about 15 minutes for the first machine, two for each one after.
  • Role: creating the connection needs Administrator or Governance lead. Any member can read the Connections page.
  • On the machine: Python 3.10 or newer, and a network path to your Oabo address.
0 of 4 steps done
  1. 1. Connect Developer machines

    Open Settings, then Connections (/settings/connections). Of the five doors choose Developer machines. Give it a name (the laptop, the team, the office) and connect.

    Expected result

    Oabo shows an ingest key once, a Mac and Linux command to paste into Terminal, a Windows command to paste into PowerShell, and under Prefer to set it up by hand? The config alone the config.toml it writes.

    Caution

    The key is not recoverable later; only its digest is stored. If you lose it, revoke the source and connect again.

  2. 2. Install with the one-command installer

    Pick your platform. Paste the whole command exactly as the page shows it.

    Open Terminal and paste the Mac and Linux command. It is wrapped in parentheses on purpose: paste all of it at once.

    What it does, in order:

    1. Checks for python3; if missing it says so and stops.
    2. Creates a private environment in ~/.oabo-collector/venv. Nothing else on the machine changes.
    3. Installs the collector from your Oabo address (/dist/oabo-collector.tar.gz).
    4. Writes ~/.config/oabo-collector/config.toml with your key, readable only by you (mode 600).
    5. Sends the first report.

    Expected result

    The last lines read Connected. Run this anytime to top up, then the path of the collector command. On macOS and Linux that is ~/.oabo-collector/venv/bin/oabo-collector; on Windows %USERPROFILE%\.oabo-collector\venv\Scripts\oabo-collector.exe.

    Python 3 is missing

    Install it from python.org (3.10 or newer, with pip included on Windows), open a new terminal, and paste the command again.

    Download failed

    The machine cannot reach your Oabo address. Check a browser on the same machine can open it, then paste the command again.

  3. 3. Send the first report by hand

    The installer already pushed once. Run a dry run to see what it counted, then push again. Nothing is sent by scan.

    Terminal
    ~/.oabo-collector/venv/bin/oabo-collector scan --since 7
    ~/.oabo-collector/venv/bin/oabo-collector push

    Expected result

    scan prints a table with one row per fingerprint, day, harness and model: input, output and cache-read tokens and a session count. push prints nothing new to push (the installer already sent it) or pushed N batch(es), M record(s) upserted.

    (no usage found in window)

    No Claude Code or Hermes session in the last 7 days on this machine. Use it, or widen the window: scan --since 30. Nothing is wrong.

  4. 4. Check the feed landed

    Back on Connections, the source you named is listed under what is connected with events received and the time of the last event. Usage from a project the workspace does not know lands in the unattributed pool, counted on the source, until someone assigns it to an AI system.

    Expected result

    The source shows a last event time and a non-zero event count. Home (/dashboard) lists the models seen under Models in usewith their tokens and cost.

    unattributed events on the source

    The collector names each project by its directory name. Map a directory to an AI system in config.toml under [mapping], or set the source's default system on the Connections page. See Usage is unattributed.

What next

Previous

Your first Scorecard in 30 minutes

Last documented 2026-11-18 against master fb17e1c5. Live release 0.3.1.