How the pieces fit

Four words carry the whole product. A machine hosts environments, an environment runs sessions, and every session works inside a nucleus.

On this page

The four nouns #

Everything in Nucarium hangs off one chain: account → machine → environment → session.

Word What it is Example
Machine A box running nucleated. agentbox
Environment One agent login running one agent server over one nucleus. A machine usually hosts several, one per client account, say. client-a
Session One agent session. On the box it is a folder holding a worktree of each repo the session added. fix-login
Nucleus The workspace folder on a box that nucleate manages and nucleated watches. /home/agent/workspace

An agent server is the vendor's own program that accepts work from your phone: for Claude Code, the Remote Control server. Nucarium does not replace it and does not sit between you and it. It runs beside it.

What runs where #

On the box, three things sit side by side:

  1. The agent server, one per environment. It starts sessions when you ask for them from the vendor's app.
  2. nucleate, a command the agent server calls to make and remove each session's folder, and that agents call as a tool to add repos mid-session.
  3. nucleated, a daemon. Once a minute it reports that the machine is alive and which agent servers are running. When a session starts, asks for you, fails or ends, a small hook writes a note that the daemon forwards.

Away from the box there is Watch. It receives those heartbeats and notes, keeps the latest state of every session, and notices when something that should have arrived did not. A box that has lost power sends nothing at all, so silence is the signal Watch is built around.

What a session looks like on disk #

The nucleus has three folders:

A nucleus
/home/agent/workspace/
  .repos/web.git               a bare clone, shared by every session
  .repos/api.git
  .worktrees/fix-login/        one session
    .workspace.json            its manifest
    AGENTS.md                  a note for the agent
    web/                       a worktree on branch workspace/fix-login
    api/
  .seeds/web/                  untracked files to copy into new worktrees

A repo is cloned once and shared. Each session gets its own worktrees of only the repos it asked for, all on one session branch, so two agents never share a checkout. The nucleus explains each part.

What a session looks like in Watch #

Watch knows a session by its id, its environment, the names of its repos, its branch, and its status:

Status Meaning
Needs input Blocked on you: a permission prompt, a request for input, or a form a tool has opened.
Failed The last turn ended in an error. Watch keeps the kind of error.
Working A turn is running.
Idle The last turn finished. Nothing is running.
Ended The session is over.

Machines and agent servers have a status of their own, from their heartbeats: online, Stale when a few have been missed, and Down when the silence has gone on too long. The inbox shows how they sort, and Deadlines gives the exact timing.

What you can use without the rest #

Each piece stands alone:

  • nucleate needs only git. No daemon, no account.
  • nucleated with no target gives you nucleated status, the same view Watch shows, read locally. It still runs the housekeeping.
  • The box recipe builds a working agent box whether or not it reports to Watch.
  • Watch needs nucleated on the box, and nothing else from this list.