brig docs

Reference

Telemetry

On this page

Some Brig commands are counted, and you can turn the counting off.

Turning it off #

brig telemetry off

The answer stays recorded on this machine. It holds whether or not Brig is the one that asks again.

DO_NOT_TRACK=1 in your environment also turns telemetry off, and it records nothing:

DO_NOT_TRACK=1 brig run claude

HULL_TELEMETRY_DISABLED=1 reaches hull unchanged and has the same effect. Both variables override an answer recorded on disk.

What is counted #

Three things are counted, each once per Brig command:

  • A sandbox boot.
  • A sandbox stop. This includes the stop inside a restart, when Brig recreates a sandbox whose shares or policy went stale. brig rm is not counted.
  • The command that hands your terminal to the agent. That is run without --json, sh, or the --json child path either one takes.

Nothing else is counted. Brig suppresses counting for its internal steps: a reachability probe, a ps lookup, cleanup work and the telemetry query.

Before you answer #

Until hull reports a recorded answer, Brig suppresses counting for a sandbox boot. This includes a boot with no terminal attached.

The command that hands your terminal to the agent is the one exception. For that command, Brig lets the hull prompt through, so you are asked before anything is sent.

Note Whether that prompt always comes before the send depends on hull code, which is outside the Brig repository.

The telemetry command #

brig telemetry status
Command What it does
brig telemetry Same as status. Changes nothing
brig telemetry status Reports the current state
brig telemetry on Records an answer, then reports the state that resulted
brig telemetry off Records an answer, then reports the state that resulted

The reported state can differ from the answer you recorded. If you record on while DO_NOT_TRACK is set in your shell, the report says off and names the variable.

brig telemetry has no --json form. Each report in Status reports is the whole output.

The report and brig telemetry --help do not name the runtime.

Status reports #

On #

telemetry: on
A sandbox boot and the command that takes your terminal each count
once. `brig telemetry off` stops it.

Off #

The wording depends on the cause.

A variable in your shell:

telemetry: off
DO_NOT_TRACK=1 in this environment turns it off, and beats any
answer recorded on this machine.

An answer you recorded with brig telemetry off:

telemetry: off
The answer is recorded on this machine. `brig telemetry on` reverses it.

A runtime that implements no telemetry reporting, which is nerdctl on Linux today:

telemetry: off
The sandbox runtime on this host sends nothing, so there is nothing
to turn off.

Not answered yet #

telemetry: not answered yet
Nothing goes out for a sandbox boot until you answer, and the first
command that hands your terminal to an agent asks the question.
`brig telemetry on` or `brig telemetry off` answers it now.

A fresh install reports this state. If hull widens what it collects, a recorded answer no longer counts as an answer. status then reports this state until you answer again.

Cannot tell #

telemetry: cannot tell
The sandbox runtime did not report a state this version of brig
recognises. Boots are not counted while that is true.

Brig reads one line from the runtime. If Brig does not recognize the phrase, it reports cannot tell and nothing is counted. An older or a newer runtime can send such a phrase.

Event contents #

hull's telemetry docs are the field-by-field reference, because hull sends the events. The description here is not checked against hull's source, which is in a separate repository.

The envelope of an event carries:

  • the product name and version
  • the OS version and CPU architecture
  • an install identifier generated on your machine
  • a timestamp
  • a checksum

One event per operation also carries:

  • which runtime operation ran, and whether it succeeded. A failure is put into a class such as network or permission. Its error text is never sent
  • which hypervisor backend booted, and whether the boot worked
  • how long the sandbox lived
  • if Brig or the runtime panics, the panic type, with a stack trace whose paths are trimmed

Never collected #

This list is a commitment from hull, and is not limited to one build:

  • guest home paths, or any host path
  • repository names, branches or remotes
  • command arguments, including the agent's own
  • agent prompts, or anything the agent read or wrote
  • secret names, secret values, or which credentials were forwarded
  • image names and registry references
  • network destinations the guest reached
  • file metadata: names, sizes, timestamps, counts

The CLI reference has the flags and exit codes of every verb, including brig telemetry. Security covers the rest of the sandbox boundary.

Type a command, a flag or an error message.