Add a node
A node is a machine that runs your tasks. You can have Jaah launch one in your own AWS account, or register a machine you already run. A machine Jaah runs for you, a Shared or Dedicated node, is bought in Billing instead: see Add.
Who can do this: adding a node requires the org admin role. Without it, New node doesn't appear.
Register a machine you run
- In the sidebar, select Directory, then the Machines tab.
- Select New node. The New node page opens beside the list.
- Pick Your machine. Clicking it moves on to the next step.
- Pick the machine's OS, then select Next.
- Enter a Name. It needn't match the machine's own name. Select Next.
- Select Create. The page shows the command that joins the machine to Jaah.
- Select Copy command, then paste the command whole into a terminal on the machine and run it.
The command holds the node's token. If you lose it before running it, use Re-issue in the node's row menu to get a new one.
The page follows the node until it's ready. It then runs your projects' tasks: see Which projects it runs.
What a Linux machine needs
Run the command in a terminal on the machine, as a user who can run sudo. The command pipes the install
into sudo bash and stops if it doesn't run as root. The machine needs:
- Ubuntu 22.04, 24.04 or 26.04, or Amazon Linux 2023, on an Intel or AMD (x86_64) or Arm (aarch64)
processor. Amazon Linux 2027 works as a preview. On another release that has
apt-getordnf, the command warns and tries anyway. Another processor type, or a system with neitherapt-getnordnf, stops it. - curl: the command is a
curlline. - Separate users. The node and its agent sessions run as their own users. A container that can't create them (one without subordinate user IDs) stops the command before it changes anything. A distrobox and Docker can, unless the container can't see the processes of the node's other users: see Fix a node that can't run work.
- CPU, memory and disk: Jaah sets no minimum. Size the machine for the builds and tests your projects run. Below 4 GB of memory, the install adds 2 GB of swap. By default, a node with less than 5 GB of free disk gets no new runners, and its tasks wait until space is freed.
The command installs, through the system's package manager: git, tmux, curl (and on Ubuntu, Python's
venv), Tailscale (it also joins the machine to your Jaah network) and the Jaah package. Once the machine is a
node, Jaah adds what runners use: Node.js 24, Docker with Compose and Buildx, the GitHub CLI, ripgrep, gitleaks,
the AWS CLI and its Session Manager plugin, plus the EFS mount helper (amazon-efs-utils) that
NodeLink needs. It never restarts the machine. Of the packages you already
have, it upgrades only Git, Node.js, npm and Docker, and only when they're older than Git 2.46, Node.js 24, npm 12
or Docker 25. On Ubuntu 22.04 and 24.04, the newer Git comes from the git-core PPA.
The machine needs outbound HTTPS (TCP 443) to:
- Your Jaah console's address, and your Jaah network's sign-in server.
tailscale.comandpkgs.tailscale.com, to install Tailscale.- Your distribution's package mirrors.
pypi.organdfiles.pythonhosted.org, for the node's Python libraries.claude.ai,downloads.claude.ai,storage.googleapis.comandregistry.npmjs.org, for the agents' command-line tools.- GitHub's website and its download host
*.githubusercontent.com,download.docker.com,awscli.amazonaws.comands3.amazonaws.com, for the runners' tools; on Ubuntu alsodeb.nodesource.com, and on 22.04 and 24.04api.launchpad.netandppa.launchpadcontent.netforgit.
No inbound port is needed. A NodeLink also needs TCP 2049 to its file system: see Set up the network for NodeLink.
In a container without systemd
The command also installs in a standard distrobox or Docker container, which has no systemd of its own. The node runs tasks, Claude sessions, Git and pull requests there as on any machine. It gets its own Tailscale connection, so the host's Tailscale is never changed, and nothing is installed outside the container.
The command prints one skipping line for each feature the container can't run:
- Start on boot. Nothing starts the node when the machine starts. The node starts again when you open a
shell in the container, or when you run
sudo jaah node startthere (jaah node startas root). - GitHub Actions runners and MicroVM sessions, which need systemd.
- NodeLink shared folders and co-located nodes, which need systemd and a machine that can mount folders.
- Tailscale SSH, when the container's Tailscale can't turn it on.
A distrobox made with --init runs systemd, so the node starts on boot there. It still gets its own Tailscale
connection, and in a rootless distrobox it skips NodeLink shared folders and co-located nodes.
While the container is stopped, the node shows as offline.
What a Mac needs
Your plan must include macOS nodes; otherwise macOS (Apple Silicon) isn't offered. Run the command in Terminal, signed in as an administrator. The Mac needs:
- macOS 14 or later on Apple Silicon. An Intel Mac stops the command.
- No Tailscale app. The command installs its own Tailscale service, which starts with the Mac. Quit and remove the Tailscale app first, if it's installed.
- CPU, memory and disk: Jaah sets no minimum. The container engine uses half the Mac's processor cores and half its memory, at least 2 of each, and its disk grows up to 100 GB. By default, a node with less than 5 GB of free disk gets no new runners.
The command brings everything else with it: Git, Node.js, Python, Tailscale and the container engine (Colima, not Docker Desktop). It needs no Homebrew and no Xcode tools.
The Mac needs outbound HTTPS (TCP 443) to:
- Your Jaah console's address, where the command downloads Jaah from, and your Jaah network's sign-in server.
claude.ai,downloads.claude.ai,storage.googleapis.comandregistry.npmjs.org, for the agents' command-line tools.- GitHub's website and its download host
*.githubusercontent.com, where the container engine downloads its virtual machine on its first start.
No inbound port is needed. A NodeLink also needs TCP 2049 to its file system, as on Linux.
A Mac can mount NodeLinks only once it allows Full Disk Access. After the
command finishes, the dialog shows the steps: in System Settings > Privacy & Security > Full Disk
Access, add /Library/Jaah/bin/jaah-anchor and turn it on. On a Mac your company manages, install the
Download profile file through your device management instead. Until then the node's NodeLinks show
Needs permission.
A Mac node can't run GitHub Actions runners or several nodes on one machine, and Jaah can't launch one in your cloud.
What a Windows machine needs
Run the command in Windows PowerShell opened with Run as administrator. The machine needs:
- Windows 10 22H2, Windows 11 or Windows Server 2022 or later, on an Intel or AMD (x64) processor.
- At least 20 GB free on the system drive.
- Nested virtualization, for Docker and NodeLink. See Turn on nested virtualization.
The command installs whatever is missing: Git for Windows, Node.js (the agents' hooks run on it), Tailscale (it also joins the machine to your Jaah network) and WSL 2. On a machine that is already a node, running the command again installs anything missing the same way. If turning on WSL 2 needs a restart, the command says so. Restart the machine, then run the same command again; it picks up where it stopped.
Turn on nested virtualization
Jaah runs Docker and mounts NodeLinks inside WSL 2, which starts a virtual machine. Without virtualization the node still comes online and runs tasks, but nothing that needs a container, and no NodeLink. Its Overview tab then shows Container engine down.
On an AWS EC2 instance:
- Use a C8i, M8i or R8i instance type, or any
.metaltype. Other families can't run WSL 2. - Select Instance state > Stop instance, and wait until it shows Stopped.
- Select Actions > Instance settings > Change CPU options, set Nested virtualization to Enable, then select Save.
- Select Instance state > Start instance.
- Run the node's command again on the machine. It picks up at the container engine.
On a physical PC: in the firmware (BIOS/UEFI) settings, turn on Intel VT-x or AMD-V (sometimes named SVM or Virtualization Technology), save, restart, and run the command again.
On another cloud's virtual machine: turn on that cloud's nested virtualization, then run the command again.
On AWS, Launch in your cloud launches a capable type and turns nested virtualization on for you.
Launch a cloud machine
Jaah can start the machine for you in your AWS, GCP or Azure account. This launches a machine your cloud provider bills you for. You need a cloud connection first.
- Select New node on the Machines tab.
- Pick Launch in your cloud. Clicking it moves on to the next step.
- Pick the Connection to launch the machine in and its Instance type, the machine's size. The list holds only the allowed types of that connection's cloud. If your plan includes Windows nodes, pick the OS: Ubuntu or Windows Server. Windows lists only the instance types that can run it. The line under the fields names where the machine launches and who bills you, for example Launches a machine in your GCP project. GCP bills you. Select Next.
- Enter a Name. Select Next.
- Select Create. The page follows the machine until it's ready.
- Select Close.
The machine comes online on its own; there is nothing to run. A Windows Server machine restarts once while
it sets itself up, so it takes longer to come online. On AWS, Windows lists only the instance types that
can run WSL 2 (C8i, M8i, R8i and .metal), and Jaah turns on nested virtualization when it launches one.
Which projects it runs
A new node joins All, so every project on All can run its tasks there as soon as it's online. There is nothing to set. To keep the node for some projects only, add it to a node group: see Run a project on some nodes only.
Related
- Read a node's status to check it came online.
- Every option on the page: Nodes.
- How nodes, worktrees and runners fit together: How nodes work.