How nodes work
A node is a machine your organization's tasks run on. It keeps working copies of your projects, called worktrees, and runs the runners that work in them. Without a node that's online, enabled and open to a project (in All, or in one of the project's node groups), no task on that project can start.
This page explains the ideas behind nodes. For the steps, see Add a node, Read a node's status and Drain or disable a node. For every column, tab and field, see Machines.
Terms
| Term | Meaning |
|---|---|
| Node | Where your tasks run. Each node runs on a host. |
| Runner | The AI agent working on a task. It runs on a node, inside one of its worktrees. |
| Worktree | A working copy of one project on one node. See How worktrees work. |
| Host | One machine. It holds one or more nodes. |
| Node group | Capacity Jaah holds for you automatically, starting and stopping cloud nodes to match it. |
| Token | The secret a node joins Jaah with. It's shown once; Re-issue replaces it. |
Where a node comes from
A node Jaah runs is bought in Billing › Products › Add-ons › Add, paid monthly by your default card and set up after payment: a Dedicated node is a machine yours alone; a Shared node runs on a machine Jaah shares between organizations, each node kept apart from the others. See Billing. On New node, Rent from Jaah only links there.
Every other node is added from New node: in the sidebar, select Directory, then the Machines tab. Then pick where the node runs:
- Launch in your cloud — Jaah launches a new machine in your AWS, GCP or Azure account, through one of your cloud connections. It comes online by itself. See How secrets work.
- Your machine — you register a laptop, desktop or server you run yourself, in any cloud or office. Jaah gives you a one-time command that joins the machine to your organization.
- Add to a host — a new node on a host your organization already has. Shown only when one of your hosts can take another node.
Your plan can also include nodes. Jaah sets them up for you when the plan starts, at no extra charge. See How plans and billing work.
A node group is the other way to get nodes: it holds a number of cloud machines for you, and the nodes it starts appear on the Machines tab like any other. Jaah's operators manage node groups and hosts; your console lists only the nodes.
Statuses and states
A node shows two separate things: whether it's reachable, and whether it takes new tasks.
Status says whether the node is reporting. Its details show ONLINE while it is and OFFLINE once it stops; on the list, a green dot marks an online node. Last seen says when it last reported, and names any kind of report that is late.
Enabled says whether it takes new tasks:
| State | What it means | What moves it on |
|---|---|---|
| Enabled | The node takes new tasks. | You select Drain or Disable. |
| Draining | No new tasks. The node disables itself when the tasks it's still running finish. | The last task finishes, or you select Cancel drain or Disable. |
| Disabled | No new tasks. Tasks already running carry on. | You select Enable. |
Neither Drain nor Disable stops a task that's already running. Delete does: it removes the node and every worktree on it, ends whatever was using them, and can't be undone.
How a node relates to the rest of Jaah
- Projects. Every enabled node is in All, so it runs the tasks of every project on All. On the Business plan, node groups keep a project on some nodes only. See Run a project on some nodes only.
- Slots. Each task running on the node gets a slot there. A node's details count them under Slots and name the tasks holding them under Held. See How worktrees work.
- Tasks and runners. When a task starts, Jaah picks a node with a free worktree for its project and launches a runner there. The node's Running tasks count shows how many are working now. See How tasks work.
- Credentials. A task on the node fetches the credentials it was given from Jaah. With NodeVault set up, each node holds your organization's NodeVault key and opens those secrets itself. See How NodeVault works.
- Model accounts. A runner reaches the AI model through one of your organization's model accounts. Accounts counts those with a working sign-in on the node; a node with none can't run tasks. See Model accounts.
Who can do what
Anyone who can view nodes sees the list and each node's details. Draining, disabling and enabling a node needs the permission to edit nodes. Adding, deleting, re-issuing a token and changing a node's projects need the org admin role. See How team and access work.