Configure your robot

A robot runs from one file, robot.toml. arc setup writes it from what it finds on the robot computer. On an enrolled robot the console keeps a copy of the file, and some settings can be changed there.

Do this after Enroll.

What setup finds and writesCopy Anchor Link

Run setup in the directory that holds the robot's files, for example ~/robot:

arc setup

For MakerMods Metal arms, run arc setup --backend makermods. It writes ./robot.toml in five steps:

Open the pictures in setup-snapshots/ to tell the wrist cameras apart. A role that no camera gets stays blank.

The arms step offers the arm type from the template. Enter keeps it. Type trossen there for Trossen arms. A side with no arm is written as "none".

The review step lists every value and where it came from. On an enrolled YAM robot with two CAN links, one RealSense camera and two USB cameras:

Values for ~/robot/robot.toml:
  arms.backend         = "yam"  (template)
  arms.can_right       = "can0"  (entered)
  arms.can_left        = "can1"  (entered)
  arms.gripper         = "linear_4310"  (template)
  arms.gravity_comp    = false  (template)
  arms.gripper_units   = "joint_rad"  (template)
  relay.host           = (blank, from the enrolled identity)
  relay.port           = 4433  (template)
  relay.cert           = (blank, from the enrolled identity)
  relay.robot_id       = (blank, from the enrolled identity)
  relay.policy_port    = 0  (template)
  cameras.exo.serial   = "123456789012"  (entered)
  cameras.wristL.index = 2  (entered)
  cameras.wristR.index = 4  (entered)

The source is template, probed (found on the machine), entered, or kept on a later run. Leave relay.port and arms.gripper_units as the template wrote them.

Setup does not open a CAN link, move an arm or connect to the relay. It cannot tell a swapped left and right arm, or swapped wrist cameras. Check that before the first run:

arc doctor --identify robot.toml

Blanks and running setup againCopy Anchor Link

The file is written even when a value is still blank. Setup then names the blanks:

[arc] WARNING: 2 value(s) still blank in ~/robot/robot.toml: cameras.exo.serial, cameras.wristL.index. Fill them in (edit the file, or run arc setup again) or arc run will not start.

Run arc setup again. It keeps the values that are set and asks only for the blanks. arc setup --force starts over from the template.

If your robot has fewer than three cameras, delete the [[cameras]] entry of each role you do not use. A role that is not in the file is off.

Without questionsCopy Anchor Link

For a scripted install, put the answers in a file. The keys have the same layout as robot.toml:

[arms]
can_right = "can0"
can_left = "can1"
[cameras.exo]
serial = "123456789012"
[cameras.wristL]
index = 2
[cameras.wristR]
index = 4

arc setup --non-interactive --answers answers.toml

With --non-interactive nothing is asked and the cameras are not searched for. A value with no answer stays blank.

How settings syncCopy Anchor Link

This applies to a robot that uses its enrolled identity. A robot that was set up before enrollment, with cert filled in under [relay], does not sync.

• The robot always runs from robot.toml. The console holds a copy.
• Upload. Each time arc run starts, before it opens an arm or a camera, the robot compares its file with the console's copy and uploads the file if it changed. arc config sync uploads it at any time.
• Change in the console. You edit settings on the robot's Robot settings page and push the change. The change waits there.
• Apply. The next time the robot starts, it writes the waiting change into robot.toml and uploads the result. Nothing is applied while the robot is running.

The certificates and the private key are never uploaded. Comments and layout are not part of the copy, so a change to a comment does not count as a change to the file.

See the stateCopy Anchor Link

arc config status

[arc] config: ~/robot/robot.toml
[arc] local hash: 9c3534ec...
[arc] baseline hash: 9c3534ec..., synced 2026-10-08T02:47:58.254604+00:00
[arc] pending change: none
[arc] state: in sync

The hashes are 64 characters long and are shortened here. The baseline is the console's copy. The state is one of:

arc doctor shows the same state on its config sync line.

Upload nowCopy Anchor Link

arc config sync

[arc] config sync: settings uploaded (9c3534ec...), synced 2026-10-08T02:47:58.254604+00:00

Do this once after arc setup if you want the settings to show in the console before the first run.

Change a setting in the consoleCopy Anchor Link

1. On the Robots page, select the robot's name in the Robots table. The Robot settings page opens. If the robot has never uploaded, it says "No settings yet."
2. The page lists the settings by section: Arms, Relay, one section per camera. Settings you can change are form fields. The others are shown with the note "set on the robot".
3. Change what you need and select Review changes.
4. The dialog lists each change with its current and new value. Select Push changes.

The page then shows Waiting for the robot's next start with the list of changes and a Discard button. The settings cannot be edited again until that change is applied or discarded.

Apply the changeCopy Anchor Link

The change is applied the next time arc run starts. To apply it without starting:

arc config pull

[arc] config sync: applied 2 changes from the console to ~/robot/robot.toml (relay.record_fps = 20, relay.record_stream = true); the old file is kept as ~/robot/robot.toml.20261007-214820.bak

• Only the lines of the changed settings change. A setting that was not in the file is added under its section. Comments and order stay.
• The old file is kept next to the new one as robot.toml.<date>-<time>.bak. To go back, copy it over robot.toml and run arc config sync.
• If the robot cannot take the change, for example because the resulting file would not load, it changes nothing and reports why. The Robot settings page then shows The robot refused the last change with the reason.
• If the robot cannot reach Northstar within a few seconds, it starts from the file as it is and tries again at the next start.

arc run --local-config-only skips the whole check for one start.

When the file was edited on the robotCopy Anchor Link

If someone edits robot.toml on the robot after a change was pushed and before it was applied, the two no longer fit. The robot applies nothing:

[arc] config sync: a change from the console is waiting, but ~/robot/robot.toml has changed since it was last synced. Nothing was applied. Run: arc config sync

The robot still starts, from its own file. To resolve it:

1. On the robot, upload the file as it is now:

   Copy

   arc config sync

   [arc] config sync: settings uploaded (38fd2f01...), synced 2026-10-08T02:48:21.543057+00:00
   [arc] config sync: a change made in the console was waiting. It now needs review in the console (Robot settings): re-apply or discard it there

2. On the Robot settings page, under Change needs review, the console shows each setting of the edit with two values: On the robot now and In the edit.

3. Tick the changes you still want and select Re-apply selected, or select Discard. A re-applied change waits for the next start like any other.

What can be changed whereCopy Anchor Link

The settings marked "On the robot only" describe the machine: what is plugged in and where. The console shows their values so you can read them. To change one, edit robot.toml or run arc setup again.

A setting that can be changed in the console can also be edited in robot.toml. The next start uploads the edit.

Changes that ask for confirmationCopy Anchor Link

Four settings change what the arms do the next time the robot starts: gripper type, gravity compensation, fault reset at start and release on exit. When a push includes one of them, the dialog adds a warning for it:

arms.release_on_exit: this changes what the arm does at its next start.

Read what the setting does in the reference below before you confirm, and tell the people on site.

Two limits on gravity compensation:

• MakerMods Metal arms do not have it. It must stay off.
• On Trossen arms it cannot be turned on from the console. Set it in robot.toml on the robot.

Tighter limits in the consoleCopy Anchor Link

The console accepts a narrower range than the file for a few numbers, so that a typing mistake cannot keep a robot from connecting:

robot.toml referenceCopy Anchor Link

These are the keys you would set. Keys that arc setup writes and that are not listed here should be left as they are.

A minimal file for an enrolled YAM robot:

schema_version = 1

[arms]
backend = "yam"
can_right = "can0"
can_left = "can1"
gripper = "linear_4310"

[relay]
host = ""
cert = ""
robot_id = ""

[[cameras]]
name = "exo"
serial = "123456789012"

[[cameras]]
name = "wristL"
index = 2

[[cameras]]
name = "wristR"
index = 4

schema_version must be 1. Paths in the file are relative to the directory that holds the file.

An option on the arc run command line overrides the file for that run. See the CLI reference.

[arms]Copy Anchor Link

Fault reset at start. A YAM motor latches fault 0xD when it stops receiving commands for too long, for example when arc run is stopped while the arms stay powered. The next start then fails while enabling the arms. With startup_fault_reset = true that fault is cleared once per motor at start. Any other fault, or a second 0xD, still stops the start, and nothing is cleared while the arms are running. Turn it on when starts fail with 0xD after a restart and cycling the arm power each time is not practical. Otherwise leave it off, so that an unexpected fault is seen.

Release on exit. With release_on_exit = true, a clean stop such as Ctrl+C or systemctl stop damps the arm joints so that an extended arm sinks slowly, waits until the arm is still, then switches every motor off. The gripper keeps holding until the motors go off. After that the arms are limp and can be moved by hand, so fold or support them before you stop the robot. If an arm is still moving after 4.5 seconds, its motors are left on in damping mode and one line says so. With false, the motors keep holding their last position after the stop, until the arm power is cycled. After a crash or a kill nothing is released, with either value.

[relay]Copy Anchor Link

On an enrolled robot host, cert and robot_id stay blank. They come from ~/.config/arc/identity/. Do not fill them in: with cert set, the robot stops using its enrollment and stops syncing.

The link defaults are right for most networks. Change them only when Northstar asks.

Policy port. The port exists for running a policy program on the robot computer. arc setup writes policy_port = 0, which is off. Keep it off unless Northstar asks you to turn it on. It can only be turned on in robot.toml on the robot, not from the console.

[[cameras]]Copy Anchor Link

One entry per camera. Each entry has a name and exactly one of serial or index.

record_resolution must be two even numbers in 16:9, no smaller than 640x360. The camera then runs at that size all the time. A camera that does not offer the size fails to open.

When a camera fails during a session, the arms hold, the operator is told which camera, and the camera restarts by itself. The operator resumes when the video is back.

NextCopy Anchor Link

Run as a service to keep the robot online, or see the CLI reference.