NORTHSTARSet up a robot
Enroll
How to connect a robot to your account with an enrollment key, what is stored on the robot, and what rotating the key does.
Enrolling registers a robot under your account. You run one command on the robot computer with your account's enrollment key. After that the robot knows which relay to connect to and can prove who it is. You do not send a file or a fingerprint to Northstar.
Do this once per robot, after Install.
Get the enrollment key
Northstar creates your account and gives you a login for the console. Each account has one enrollment key, shared by all its robots.
- Sign in to the console and open Robots.
- Find Enrollment key and select Show key.
- Copy the key. Select Hide key when you are done.
The key starts with nsk_, followed by your account id and 32 more characters. Anyone who has it can add a robot to your account, so treat it like a password.
Enroll the robot
Run arc enroll on the robot computer, with nothing after it. It asks for what it needs:
arc enroll[arc] This registers this robot under your account and stores its identity in ~/.config/arc/identity.
[arc] You need your account's enrollment key. In the console, open your account page and, under Enrollment, select Show key.
Paste the enrollment key and press Enter: nsk_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
[arc] key read: it is for account acme
Robot name, as the console will show it [jetson]: cell-1
Arm type:
1. yam
2. trossen
3. makermods
4. feather
Type the number or the name: 1
[arc] About to enroll:
[arc] account acme
[arc] robot name cell-1
[arc] arm type yam
[arc] identity ~/.config/arc/identity
Enroll this robot? [Y/n]:
[arc] enrolling 'cell-1' (yam) ...
[arc] enrolled: robot acme-cell-1, account acme
[arc] relay: relay.example.com (check-in port 443)
[arc] identity: ~/.config/arc/identity (robot key mode 0600)
[arc] Next: arc setupWhat to know about the questions:
- The key. Paste the key alone, or the whole command line the console shows. Spaces and quotes around it are ignored. The key is shown as you paste it. If the paste is not a key, or the server refuses it, the command asks again, up to three times.
- Robot name. The name in square brackets is the computer's hostname. Press Enter to use it, or type another.
- Arm type. Type the number or the name. When
./robot.tomlexists, its arm type is used and the question is skipped. - The summary. Press Enter or type
yto enroll. Any other answer stops without changing anything.
Pasting the key at the question keeps it out of your shell history.
In a script
Give the key and the answers as arguments. The command asks nothing it has an answer for, and without a terminal a missing answer is an error.
arc enroll nsk_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --name cell-2 --backend yam --yes[arc] enrolling 'cell-2' (yam) ...
[arc] enrolled: robot acme-cell-2, account acme
[arc] relay: relay.example.com (check-in port 443)
[arc] identity: ~/.config/arc/identity (robot key mode 0600)Options
| Argument | Meaning |
|---|---|
KEY | The account's enrollment key. Asked for when left out. |
--name NAME | The robot's name in your account. Default: the computer's hostname. |
--backend BACKEND | The arm type: yam, trossen, makermods or feather. Default: the one in ./robot.toml when that file exists, otherwise asked. |
--yes | Replace an existing identity, and enroll, without asking. |
arc enroll --help prints the same list.
Robot name and robot id
The robot id is your account id, a hyphen, and the robot's name in lower case, with every run of other characters turned into one hyphen. In account acme, the name cell-1 gives acme-cell-1 and the name Cell 3 East gives acme-cell-3-east. The id is what appears in the console and in session records.
Give each robot its own name. If a second computer enrolls under a name that is already used in the account, it takes over that robot id.
What is stored on the robot
Enroll creates the robot's own keypair on the robot computer. Only the public certificate is sent; the private key never leaves the machine. The result is one directory, readable only by your user:
~/.config/arc/identity/
robot_cert.pem this robot's certificate (public)
robot_key.pem this robot's private key, mode 0600
relay_cert.pem the relay's certificate, received from the server
identity.json robot id, account id, relay host, check-in port, enrolled timeidentity.json after the first example above:
{
"robot_id": "acme-cell-1",
"account_id": "acme",
"relay_host": "relay.example.com",
"checkin_port": 443,
"enrolled_at": "2026-10-08T02:17:40Z"
}arc setup, arc doctor and arc run read this directory. You do not copy these values into robot.toml: on an enrolled robot the relay host, relay certificate and robot id stay blank there.
Nothing is written until the server has accepted the enrollment. A failed attempt leaves an existing identity as it was.
Do not copy the identity directory to another robot. Enroll each robot on its own computer.
Check the enrollment
arc doctor reports the identity. On an enrolled robot with a robot.toml:
arc doctor robot.toml[arc] PASS identity: robot acme-cell-1, account acme, cert sha256 845d2751052ad3bce73de8e9972db2d5f4773749f20c3ff1fb4031245117fcd2, relay cert expires 2026-11-06; in use
[arc] PASS relay cert: ~/.config/arc/identity/relay_cert.pem (expires 2026-11-06)
[arc] PASS client cert: ~/.config/arc/identity/robot_cert.pem (sha256 845d2751052ad3bce73de8e9972db2d5f4773749f20c3ff1fb4031245117fcd2)These are the first lines after the config line; the arm and camera checks follow. The hash and the date are from an example robot and will differ on yours.
On a robot that is not enrolled the line is a SKIP:
[arc] SKIP identity: not enrolled (no identity in ~/.config/arc/identity); arc enroll creates oneIn the console, the robot is listed in the Robots table on the Robots page with its name, id, arm type, the date it enrolled and its state. The state is Offline until arc run is connected, then Online.
Enroll again
Running arc enroll on a robot that already has an identity asks first:
[arc] this robot is already enrolled: robot acme-cell-2, account acme (~/.config/arc/identity)
Replace it? The old robot key is deleted. [y/N]:Answer y and the enrollment goes on as above.
Any answer other than y or yes keeps the identity:
[arc] ERROR: kept the existing identity; nothing was changed--yes skips the question, for a script. With the same name the robot keeps its robot id and gets a new keypair.
You need to enroll again after the key is rotated or after the robot is revoked.
Rotate the key
Rotate the key when it may have leaked, or when someone who had it should no longer be able to add robots. On the Robots page, under Enrollment key, select Rotate key and confirm. The console shows the new key and lists the robots that went offline.
Rotating the key takes every robot that enrolled with the old key offline. Each one stays offline, with the state Revoked in the Robots table, until you enroll it again with the new key. The old key stops working right away.
After a rotation, on each robot:
arc enroll nsk_acme_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --name cell-2 --backend yam --yesUse the same --name as before so the robot keeps its id. Then restart arc run.
The old key is refused:
[arc] ERROR: enrollment key not accepted: it is unknown or revoked; check the key in your account (server: enrollment key not accepted)Revoke one robot
To take a single robot out of your account without touching the others, select Revoke in that robot's row of the Robots table. The robot is disconnected right away and its state becomes Revoked. The enrollment key does not change. To bring the robot back, enroll it again.
Robots set up before enrollment
A robot that was set up with relay values in its configuration file (a [relay] section in robot.toml with cert filled in) keeps working as it is. It does not need to enroll. In the console its Enrolled column reads Registered by Northstar, and rotating the key does not affect it.
If enroll fails
| Message | What to do |
|---|---|
enrollment key not accepted: it is unknown or revoked | Check the key against Show key in the console. A key that was rotated no longer works. |
this account is suspended; contact Northstar | Contact Northstar. |
too many enrollment attempts | Wait for the time the message gives, then try again. |
cannot reach the enrollment server | Check the robot computer's network connection. |
already enrolled; pass --yes to replace the identity | The command had no terminal to ask on. Run it in a terminal, or add --yes. |
See Troubleshooting for more.
Pointing at a different server: the address of the enrollment server is built into the command. Set ARC_ENROLL_URL only when Northstar gives you another address to use.
Next
Configure your robot with arc setup, or follow the rest of the Quickstart.