Reference

Telemetry

Brig sends anonymous usage events and crash reports, and you can turn them off.

Turning it off #

brig telemetry off

Brig records the answer on this machine. hull, the runtime Brig drives on macOS, reads the same answer, so it holds whether or not Brig is the caller.

To turn telemetry off without a recorded answer, set DO_NOT_TRACK=1 in your environment:

DO_NOT_TRACK=1 brig run claude

HULL_TELEMETRY_DISABLED=1 has the same effect. Both variables must be the exact string 1, and both override an answer recorded on disk.

What is counted #

Brig sends two kinds of event itself, on macOS and on Linux:

• One event per command. It names the command, the agent it ran, and whether it worked. A command that failed carries the class of the failure, never its message.
• A crash report when Brig panics.

A brig run or brig sh that hands your terminal to the agent counts as ok once the handover starts, whatever the agent does after it.

These invocations send no command event:

• brig telemetry, which is how you answer
• the shell completion script, which runs in every new shell
• a bare brig, a mistyped global flag, and a spelling Brig has removed
• a command stopped by Ctrl-C or a signal before it hands your terminal to the agent. A panic sends its crash report instead

Before you answer #

Nothing is sent until someone answers.

The first brig run or brig sh on a terminal asks the question before anything boots, when Brig runs in the foreground of that terminal:

brig collects anonymous usage events and crash reports to help us
improve it: command names, which agent and backend you run, OS and tool
versions, and stack traces. An agent of your own goes out as a salted
hash of its name. File paths, arguments and image names are never sent.
Docs: https://github.com/brig-sh/brig/blob/main/docs/telemetry.md
Enable telemetry? [Y/n]

Enter or y answers yes, and n answers no. Ctrl-D is not an answer, and the question stays open.

Any other command, a script, a pipe, a background job, CI, --json and -q never ask, and send nothing until there is an answer.

When Brig or hull widens what it collects, a recorded yes no longer counts as an answer. The next brig run or brig sh on a terminal asks again, and nothing is sent until you answer.

The telemetry command #

brig telemetry status

The reported state can differ from the answer you recorded. If DO_NOT_TRACK is set in your shell, brig telemetry on still reports off and names the variable.

The report and brig telemetry --help do not name the runtime, so you can opt out without knowing which binary sends. brig telemetry has no --json form.

Status reports #

The report is one of three states: on, off, and not answered yet. Under the state, ↳ lines say what decided it, and → lines say what to type to change it. When the machine has an install identifier, the report names it.

On #

telemetry: on
  ↳ each brig command counts once
  ↳ on macOS, a sandbox also reports its boot and how long it ran
  ↳ install id: 12345678-90ab-4cde-8f01-234567890abc
  → to turn it off:  brig telemetry off

Off #

A variable in your shell:

telemetry: off
  ↳ DO_NOT_TRACK=1 in this environment turns it off
  ↳ it beats any answer recorded on this machine
  ↳ install id: 12345678-90ab-4cde-8f01-234567890abc
  → to let the recorded answer decide:  unset DO_NOT_TRACK

An answer you recorded with brig telemetry off:

telemetry: off
  ↳ the answer is recorded on this machine
  ↳ install id: 12345678-90ab-4cde-8f01-234567890abc
  → to turn it on:  brig telemetry on

Not answered yet #

A fresh install reports this state. So does an answer to a shorter list than the current one.

telemetry: not answered yet
  ↳ nothing goes out until you answer
  ↳ the first `brig run` or `brig sh` on a terminal asks the question
  → to turn it on:   brig telemetry on
  → to turn it off:  brig telemetry off

Every event carries the install identifier, so it finds the events this machine sent, for example when you ask for them to be deleted. Asking for the report creates no identifier.

Where the answer lives #

The answer and the install identifier are in ~/.hull/telemetry.json. You can read or delete that file at any time. Deleting it rotates the install identifier and forgets the answer.

Brig never waits on the network. When a command ends, or right before it hands your terminal to the agent, Brig writes its event to ~/.hull/outbox/ and starts brig telemetry flush in the background. That process uploads the outbox and the crash reports in ~/.hull/crashes/, then exits, within about 30 seconds. It has no terminal, prints nothing, and only one runs at a time. An event it cannot send stays queued, and the next upload tries again.

A build of Brig with no endpoint, such as one from go install, sends nothing and queues nothing. brig telemetry off empties the queues.

These are hull's files, so one answer covers both tools. On Linux, where hull does not run, Brig creates ~/.hull for these files alone. Brig run under sudo with your HOME leaves no files there.

Event contents #

Every event carries:

A command event also carries:

agent_hash lets one profile of your own be counted across machines without sending its name. The salt is in Brig's source, so anyone who guesses the name can compute the same hash. A name that is easy to guess is as good as sent.

A crash report carries the command, the Go type of the panic, and a stack trace whose paths are trimmed. It never carries the panic message, which can hold a path.

The events hull sends for a sandbox carry Brig's version, and hull's own as runtime_version. hull's telemetry docs are the field-by-field reference for those, and for the transport.

Never collected #

• 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

Related pages #

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