Skip to main content

How-to install a robot on a Linux VPS

A robot on a VPS has no logged-in desktop user to start it, so two things differ from a desktop install: it authenticates with a robot token instead of your password, and it is started by systemd instead of the tray application.

Prerequisites​

  • Ubuntu 22.04 or 24.04 on AMD64 (the distributions the .deb supports)
  • sudo access over SSH
  • A robot created in the Admin Console, and a robot token for it

1. Install the package​

Download the current .deb from robomotion.io/downloads, then:

sudo dpkg -i robomotion_<version>_amd64.deb
sudo apt-get install -f -y

Confirm the CLI is on your PATH:

which robomotion-deskbot
robomotion-deskbot --version

2. Create the robot and its token​

In the Admin Console → Robots, create a robot and generate a robot token for it. Note the robot's ID as well — token authentication needs both.

3. Connect once, interactively, to verify​

robomotion-deskbot connect \
  -w rpa.acme.inc \
  -r 624609c6-1a27-458f-ace5-3889dc554e28 \
  -t <robot-token> \
  --no-attach

You should see the robot report connected. Stop it with Ctrl-C once you have.

note

--token requires both --robot and --workspace. If either is missing the command just prints its usage and exits.

4. Keep the token off the command line​

Anything passed as a flag is visible to every user on the box through ps and /proc/<pid>/cmdline. The robot reads these environment variables when the matching flag is absent, which is what you want for a service:

VariableEquivalent flag
ROBOMOTION_WORKSPACE-w, --workspace
ROBOMOTION_ROBOT_ID-r, --robot
ROBOMOTION_ROBOT_TOKEN-t, --token
ROBOMOTION_USER_EMAIL-i, --identity

Flags take precedence — the environment is consulted only when the flag is empty.

Put them in a root-only file:

sudo mkdir -p /etc/robomotion
sudo tee /etc/robomotion/robot.env >/dev/null <<'EOF'
ROBOMOTION_WORKSPACE=rpa.acme.inc
ROBOMOTION_ROBOT_ID=624609c6-1a27-458f-ace5-3889dc554e28
ROBOMOTION_ROBOT_TOKEN=<robot-token>
EOF
sudo chmod 600 /etc/robomotion/robot.env

5. Run it as a systemd service​

/etc/systemd/system/robomotion-robot.service
[Unit]
Description=Robomotion Robot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=robomotion
EnvironmentFile=/etc/robomotion/robot.env
ExecStart=/usr/bin/robomotion-deskbot connect --no-attach --log-level info
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Adjust User= and the ExecStart= path to match your machine — which robomotion-deskbot gives you the latter. Then:

sudo systemctl daemon-reload
sudo systemctl enable --now robomotion-robot
sudo systemctl status robomotion-robot
journalctl -u robomotion-robot -f

6. Decide whether the robot needs a display​

This is the step most VPS installs get wrong.

  • Headless browser flows need no display. Nothing extra to do.
  • Headed browser flows and any GUI automation need a display. On a bare VPS there is neither an X11 nor a Wayland session, so Chrome has nowhere to put a window and exits before its DevTools endpoint opens.

Give it a virtual display with Xvfb:

sudo apt-get install -y xvfb
/etc/systemd/system/robomotion-robot.service (excerpt)
ExecStart=/usr/bin/xvfb-run -a --server-args="-screen 0 1920x1080x24 -ac +extension RANDR" \
          /usr/bin/robomotion-deskbot connect --no-attach --log-level info

When only DISPLAY is set, the robot selects Chrome's X11 backend for you — you do not need to pass browser flags yourself. If you set WAYLAND_DISPLAY instead, Chrome's own default is already correct.

warning

Xvfb has no window manager, so nothing ever receives focus. Flows that depend on window focus or on reading the real screen are better served by a desktop session (VNC or RDP) than by Xvfb.

Useful flags for unattended robots​

FlagWhy it matters on a server
--no-attachSkips attaching to the Flow Designer. Faster, and correct for a robot nobody is watching.
--lockLock mode refuses to run any flow that is not already cached — a hardening measure for production robots.
--log-leveldebug, info, warning, error, off.
--logdirSend logs somewhere you actually rotate.
--proxy[<scheme>://]<host>[:<port>] if the VPS reaches the internet through a proxy.
--send-crash-dumpsForwards crash dumps to Robomotion.

Verify​

In the Admin Console → Robots, the robot should show as connected. Reboot the VPS and confirm it reconnects on its own:

sudo reboot
# then, once it is back
systemctl is-active robomotion-robot

Next steps​