Help Center · Desktop agent

Connect a server over SSH

A Linux machine with no desktop — a server you reach over SSH — connects with the same browser sign-in as any other computer, except that you open the link on a phone or laptop and type the code it gives you into the terminal.

Who this is for

Anyone setting up the Linux agent over SSH, on a headless box, or in a virtual machine with no desktop session. If the machine has a desktop in front of you, read Sign in with your browser instead: there, the browser opens by itself.

Before you start

The Linux agent is on the machine.
You can open a link and sign in to WorkMonitor on some other device — your phone or your own laptop is fine. It does not have to be on the same network as the server.

Steps

In the terminal on the server, run the setup command: workmonitor-agent setup. Over SSH it works out that there is no display and goes straight to the code way; you can also ask for that explicitly with workmonitor-agent setup --code.
Press Return at Workspace URL unless your company runs WorkMonitor on its own server, in which case type that address.
It prints a link and waits. Open the link on your phone or laptop and sign in there.
The page asks whether to connect the computer and names it. Check it, then select Connect, then select Show a code.
Type the code into the terminal and press Return. Codes are not case-sensitive and the dash is optional.
The terminal asks Connect this machine as [your name] ([your email]) in [workspace]? [y/N] — type y and press Return.

It finishes with ✓ This machine is connected, then prints what this box can actually capture, which on a server is usually nothing but the typed work record. Start it with workmonitor-agent, or workmonitor-agent --install-autostart to start it at login.

What is written, and when

Nothing is written until you answer y. Pressing Return on its own, typing anything else, pressing Ctrl-D, or pressing Ctrl-C all end it with Nothing was connected. and leave no file behind. Once you do, the agent stores its own credential where only your user account can read it.

Read the question rather than typing y through it. It names the person and the workspace the server is about to record for, and it is the only thing standing between a link someone sent you and your server reporting into their workspace.

For scripts and images

Setup asks a person a question, so it refuses to run with its input coming from a pipe or a file: it exits straight away, before printing anything, and tells you to use one of the two paths that are meant for scripts. A build step that tried it would otherwise sit there for twenty minutes waiting for a code nobody is going to type.

The two script paths:

workmonitor-agent setup --token-stdin reads an enrollment token from standard input. Generate the token on the Get the agent screen.
ENROLLMENT_TOKEN=… workmonitor-agent enrols at start-up with no terminal at all, which is the one to use in a container image.

Neither shows a name to confirm, because neither has anybody there to read it.

Exit codes

0 — connected.
1 — not connected: refused at the question, the link expired, or the workspace said no.
2 — nothing was attempted: no terminal, or an option it did not understand.
130 — you pressed Ctrl-C.

If it doesn't work

"Couldn't reach the workspace." The server can't reach the API host. Check the machine's outbound access, and the address you typed at Workspace URL.
"That code isn't right." Retype it — it is eight characters, and the dash is optional. Five wrong tries lock the request; start again with workmonitor-agent setup.
"That code expired." A code is good for about 5 minutes. Select Show a code again on the page.
"That request expired. Start again." The whole request lasts 20 minutes from the moment you ran setup.
The link is too long to copy out of your terminal. It wraps across two lines in an 80-column window; select all of it, or widen the window first. It is one link, not two.
You want the old way. workmonitor-agent setup --password signs in with your work email and password, and asks for your two-factor code if your account has one.

Sign in with your browser
Which operating systems does WorkMonitor support?
Your devices
The agent isn't connecting