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.
Start hereOn 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:
- The agent server, one per environment. It starts sessions when you ask for them from the vendor's app.
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.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:
/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:
nucleateneeds onlygit. No daemon, no account.nucleatedwith no target gives younucleated 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
nucleatedon the box, and nothing else from this list.