Runners and cloud environments

A runner is the process that starts harnesses (runtimes) and does the work.

• Local runner: built into the desktop client. It needs no setup.
• Cloud runner: a standalone runner on a server that stays online. People can close their client while it works.
• Workstation runner: a standalone runner on an authorized computer on your team. Use it for work that needs the files or tools on that computer. It connects with the same steps as a cloud runner.

All three are the same runner program. See Architecture: Runner internals.

Connect a cloud runner

Before you start: a server that can reach your Hub over HTTPS, and permission to manage runners (runner.manage), or your own cloud environment.

1. In the client, open Settings → Cloud environments and choose Set up executor. Admins can also connect shared runners in the admin console under Execution network.
2. Choose Copy setup command. The command contains a key for this machine and is shown only once.
3. Run the command in a terminal on the server.
   • Linux installs the runner under /opt/soduwork-runner and registers a systemd service. It needs root or sudo.
   • Windows uses a PowerShell installer.
4. Back in Cloud environments, choose Refresh. The runner appears when it connects.

The key gives access to this runner. Use it only in a terminal on the target computer, and never post it in a chat or ticket. To replace it, rotate the credential from the same page.

To remove the runner: sudo bash runner-install.sh --uninstall.

Runner options

The installer writes the runner's configuration. These options are also available when you run runner_main.py yourself:

Option	Environment variable	Meaning
--hub	SODUWORK_HUB	Hub address
--key	SODUWORK_RUNNER_KEY	This machine's key
--id	SODUWORK_RUNNER_ID	Runner ID
--tags	SODUWORK_RUNNER_TAGS	Comma-separated tags, for example linux,intranet. Workflow nodes can require tags
--work-root	SODUWORK_WORK_ROOT	Where tasks and first clones are placed
--data-root	SODUWORK_DATA_ROOT	The runner's sessions and logs
--max-concurrent	SODUWORK_RUNNER_MAX_CONCURRENT	Upper limit for concurrent work, 1 to 20. The actual value adapts to CPU and memory
--doctor		Check the CLIs, terminal and bundled Skills, then exit

Install harnesses on the runner

Each runner installs its own harnesses. Install them with the same account the runner service uses, make sure Node.js, npm and the harnesses are on that account's PATH, then restart the runner and check its connection. systemd doesn't load interactive shell profiles, so a PATH set only in ~/.bashrc (for example by nvm) isn't seen.

Managing runners

In the client's Cloud environments, people can rename, pause or delete runners they own. In the admin console, Execution network → Runner devices lists all runners, and admins can change availability and reassign them.

When no runner can take a cloud chat, the client explains why: offline, missing harness, not signed in, missing capability or full.

Security

• Connect runners only to Hubs you trust.
• The Hub never gets the runner's Docker socket or SSH credentials.
• Secrets used by plugins stay on the runner and are injected only into the step that needs them (Capabilities and secrets).

harness harnesses runtime runtimes 底座