What leaves the box, and what never does

Watch knows that your agent is waiting, never what it asked. This is the full list of what is sent, everything that is not, and how that is enforced.

On this page

The promise #

Nucarium Watch sees which agent is doing what, where and since when — never what it was told or what it wrote.

That sentence is the whole of it. The rest of this page is the detail behind each half.

What is sent #

nucleated sends two kinds of message. This is everything in them.

Sent Never sent
Machine name, environment label Prompts, messages, session titles
Session id, vendor session id Tool inputs and outputs
Lifecycle event type, error kind Transcript paths or contents
Repo names in the session, branch Diffs, file contents, file paths beyond the repo name
Timestamps (box clock, as diagnostic) Environment variables, secrets, tokens
Disk %, load, uptime, memory pressure, live agent servers Usernames, hostnames of other machines, IP addresses (beyond what HTTPS reveals)

Every field of a heartbeat #

Once per heartbeat interval, for the machine as a whole:

FieldTypeRequiredMeaning
machineobjectRequired
machine.disk_used_pctnumberRequired0 to 100.
machine.load_1mnumberRequired0 to 100000.
machine.uptime_sintegerRequiredAt least 0.
machine.memory_pressure_pctnumberOptionalShare of recent time some task stalled on memory. Omit where the box cannot measure it. 0 to 100.
environmentsarray of objectRequiredEvery environment the daemon is configured to run. env_id values are unique. At most 40 items.
environments[].env_idstringRequiredThe environment's name on the box, unique within its machine. Lower case letters, digits, ., _ and -. Must match ^[a-z0-9][a-z0-9._-]{0,63}$.
environments[].server_alivebooleanRequiredWhether the environment's agent server process is running right now.
daemon_versionstringOptionalMust match ^[0-9A-Za-z.+-]{1,32}$.
client_tsstring (date-time)RequiredThe box's clock. A diagnostic; never used for a deadline.

Any field that is not in this table is rejected, and the request with it.

Every field of a session event #

One per thing that happens to a session: it starts, takes a prompt, stops to ask, finishes, fails, ends. Events are sent in batches of these:

One lifecycle event. Metadata only; there is no field for content.

FieldTypeRequiredMeaning
event_idstringRequiredGenerated on the box, unique per event. Watch deduplicates on it. Must match ^[A-Za-z0-9_-]{8,64}$.
env_idstringRequiredThe environment's name on the box, unique within its machine. Lower case letters, digits, ., _ and -. Must match ^[a-z0-9][a-z0-9._-]{0,63}$.
session_idstringRequiredMust match ^[A-Za-z0-9._:-]{1,128}$.
bridge_session_idstringOptionalThe agent vendor's own id for the session, when the box knows it. Must match ^[A-Za-z0-9._:-]{1,128}$.
typestring, one of the values listedRequiredWhat happened to the session, and the status it moves to: One of: session_start, user_prompt_submit, activity, permission_prompt, input_prompt, elicitation_prompt, stop, stop_failure, session_end.
reposarray of stringOptionalThe repos in the session, as owner/name or name. At most 32 items.
branchstringOptionalA git branch name. No spaces or control characters. Must match ^[A-Za-z0-9._/@+=#-]{1,255}$.
error_kindstringOptionalWith stop_failure, a short machine-readable kind such as rate_limit. Never a message. Must match ^[a-z0-9_.-]{1,64}$.
client_tsstring (date-time)RequiredThe box's clock when the event happened. Orders events within a session; never used for a deadline.

Any field that is not in this table is rejected, and the request with it.

These two tables are not written by hand. They are drawn from the API's own contract when this site is built, so they cannot fall behind it. The API reference has the same contract in full.

The machine's name is not in either message. Watch knows which machine is speaking from its token, and the name is the one you gave it when you signed the box in.

What is never sent #

Nothing about what a session said or did:

  • A prompt, a reply, or a session's title.
  • What a tool was asked to do, or what it returned.
  • A transcript, or where one is kept.
  • A diff, a file's contents, or a file's path. A repo's name is sent; nothing inside it is.
  • An error's message. Only a short fixed word for its kind, such as rate_limit.
  • An environment variable, a secret, or a token.
  • A username, the name of any other machine, or an IP address.

There is no field that could carry any of these. That is not a filter that might miss something. It is the absence of anywhere to put it.

How it is enforced #

The payload is built from a list, not trimmed from a copy. nucleated does not take what the agent hands a hook and strip out the private parts. It starts with nothing and adds named fields, one at a time, from the list above. A field that is not on the list is never read, so it cannot be sent by accident. What is kept from an event shows where each one comes from.

Every value is checked before it is written down. A branch name has to look like a branch name; an error kind has to be one short word. A value that does not fit is left out, so a field cannot be used to smuggle a sentence.

A test gates every release. It feeds every hook event a payload with a sentinel string in every content-bearing field, in the working directory's path and in the environment, and then proves no sentinel is in the spool, in the daemon's own records, or in any request it makes. If that test fails, the daemon does not ship.

Watch refuses what it does not expect. The API is strict in the same way: a request with a field the contract does not name is rejected whole, and nothing from it is stored. If a future bug on the box added a field, Watch would turn it away.

The token can only write. The machine token lets a box report on its own machine. It cannot read anything, from that machine or any other. Someone who took it from a box could send false heartbeats for that one box, and could learn nothing.

You can read it yourself. The tools on the box are open source. Every note waits in a folder as a plain file before it is sent, and nucleated status prints what Watch is told. Try one by hand shows a note, sentinel and all.

Watch cannot act on a box #

Watch has no command channel. It never connects to a box; boxes connect to it, to write. Nothing in Watch can start, approve, stop or message a session, restart a server, or run anything on your machine.

So a problem at Watch, whatever it was, could not reach your code or your agents. The worst it could do is fail to tell you something. Anything that acts stays in your agent vendor's own app, behind that vendor's sign-in.

What to know before you rely on it #

Names are sent as they are. Repo, branch, machine and environment names go to Watch unaltered, because an inbox of aliases is hard to read. If a repo's name is itself a secret, that matters, and the answer is to run nucleated with no target.

HTTPS reveals an IP address. No IP address is in any message, but any request shows the server it reaches where it came from. That is true of every service on the internet, and this page says so instead of pretending otherwise.

The box's clock is sent. Watch never uses it to decide anything. It is kept so a late batch can be put in order, and so a wrong clock can be seen.

What Watch knows about you #

You sign in to Watch with GitHub. When you do, Watch asks GitHub who you are and keeps four things: your GitHub user id, your handle, your name if you have set one, and your primary verified email address. It asks for nothing else: no repositories, no organisations, no code. The access GitHub grants is used once, at sign-in, and then thrown away; Watch stores no GitHub token.

Keeping and deleting #

Watch keeps ended sessions and fired alerts for as long as your plan says: 7, 30 or 90 days.

Deleting an environment deletes what Watch stored for it. Deleting your account deletes every machine, environment, session, token, alert destination and alert it owns, within 30 days, and Watch confirms by email.

Signing a box out (nucleate logout) revokes its token and deletes it from the box. What the box already reported stays in your account until you delete the machine.

If nothing may leave #

Do not sign the box in. nucleated with no target opens no connection and sends nothing, and still gives you the local status view and the housekeeping. Targets describes it.