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 assigned to a project, 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 Nodes.
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 token replaces it. |
Where a node comes from
You add a node from Add node on the Nodes page, and pick where it runs:
- Host with Jaah — Jaah runs the machine, paid by card monthly or by the hour. A Dedicated machine is yours alone; a Shared node runs on a machine Jaah shares between organizations, each node kept apart from the others.
- Use my cloud account — Jaah launches a new machine in your AWS account, using one of your AWS credentials. It comes online by itself. See How credentials work.
- Use my own machine — you register a machine you run yourself. Jaah gives you a one-time command that joins the machine to your organization.
- Add to one of my hosts — a new node on a host your organization already has.
A node group on the Groups tab is the other way to get nodes: it holds a number of cloud machines for you, and the nodes it starts appear on the Nodes tab.
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 the Health & Metrics tab says which kind of report has gone STALE.
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. A node runs only the projects you assign it, on its Projects tab or the project's own Worktrees tab. A node with no project runs no tasks. See How projects work.
- Worktrees. Each assigned project gets worktree slots on the node. The Worktrees count on a node opens them on the Worktrees page. 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 Runners count shows how many are working now. See How tasks work.
- 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.