Install and run the collector
Put the oabo-collector on one machine, send its first report, and check that the feed landed.
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.
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.tomlit writes.Caution
The key is not recoverable later; only its digest is stored. If you lose it, revoke the source and connect again.
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:
- Checks for
python3; if missing it says so and stops. - Creates a private environment in
~/.oabo-collector/venv. Nothing else on the machine changes. - Installs the collector from your Oabo address (
/dist/oabo-collector.tar.gz). - Writes
~/.config/oabo-collector/config.tomlwith your key, readable only by you (mode 600). - Sends the first report.
Open PowerShell and paste the Windows command. It is one line on purpose: PowerShell runs a pasted multi-line script as separate commands, so one line is the only way the install either happens whole or not at all.
What it does, in order:
- Finds
pythonorpython3; if neither exists it says so and stops. - Creates a private environment in
%USERPROFILE%\.oabo-collector\venv. - Installs the collector from your Oabo address.
- Writes
%USERPROFILE%\.config\oabo-collector\config.tomlwith your key. - Sends the first report.
Note
On Windows the config file is not locked down the way the Mac and Linux installer does with mode 600. Keep it inside your own user profile, as the installer does.
Open a terminal and paste the Mac and Linux command. Same steps as macOS; the paths are the same.
- Checks for
python3. - Creates
~/.oabo-collector/venv. - Installs the collector from your Oabo address.
- Writes
~/.config/oabo-collector/config.toml, mode 600. - Sends the first report.
Could not build the environment
On Debian or Ubuntu the venv module is a separate package. Run
sudo apt install -y python3-venv, then paste the command again.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.
- Checks for
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 pushPowerShell& "$env:USERPROFILE\.oabo-collector\venv\Scripts\oabo-collector.exe" scan --since 7 & "$env:USERPROFILE\.oabo-collector\venv\Scripts\oabo-collector.exe" pushshell~/.oabo-collector/venv/bin/oabo-collector scan --since 7 ~/.oabo-collector/venv/bin/oabo-collector pushExpected result
scanprints a table with one row per fingerprint, day, harness and model: input, output and cache-read tokens and a session count.pushprints 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. 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.tomlunder[mapping], or set the source's default system on the Connections page. See Usage is unattributed.
What next
- Keep it current without remembering to: Run the collector on a schedule.
- Every command, option and path: oabo-collector command reference.
- Other machines or other feeds: Choose how to connect.