Linux
The Linux agent runs on the machine where your bots are executed. It connects to the Sinfonia orchestrator over HTTPS, receives executions from the queue and sends logs and status back. It supports Linux distributions.
Note
A single executable
The agent ships as a single static binary, agent. There is no installer, runtime or extra library to set up: just copy the file to the machine and run it.
- No installation: a single executable that already bundles everything the agent needs to run.
- Continuous execution: can be set up as a systemd service, to start with the server and recover from failures.
- Multiple architectures: works on x86_64 and ARM64 processors.
Note
The agent needs no installation, but your bots still need their own dependencies on the machine, such as Python 3.12+ for Python bots or Node 22+ for JavaScript bots. Check the prerequisites and hardware requirements, especially network access to the orchestrator.
Download the agent
Go to https://sinfonia.live/agents and click the download icon in the upper left corner. Fill in the fields:
Agent Name
- Description: Name used to identify the agent on the platform. Use something that points to the machine, for example
LNX-FINANCE-01.
OS
- Description: Operating system of the machine where the agent will run.
- Available options:
Linux,Windows. SelectLinux.
Token
- Description: Token that authenticates the agent with the orchestrator.
- How to obtain: By default the platform generates a
mastertoken when your account is set up. You can also create tokens in the tokens section.
Auto Update
- Description: Whether the agent updates itself when a new version is available.
- Available options:
Enabled,Disabled.
Copy the files to the machine
Upload the downloaded files to the machine where the agent will run and keep them all in the same folder. The agent needs read and write permission on that folder.
Start the agent
mkdir -p /home/<user>/sinfonia
# copy the downloaded files into this folder
cd /home/<user>/sinfonia
chmod +x agent
./agentThis command runs the agent in the foreground, which is useful to validate the connection. To keep it running continuously, set it up as a service or use one of the other options described in Keeping the agent running.
Confirm the connection
Go back to https://sinfonia.live/agents. The agent should appear with the chosen name and ONLINE status. From then on it can be selected when publishing bots and configuring triggers.
Keeping the agent running
Running ./agent directly in the terminal is fine for testing, but the agent stops when the session ends. For continuous use, choose one of the options below:
| Option | Survives the end of the session | Starts with the server | Restarts if the process dies | Best for |
|---|---|---|---|---|
| systemd service | Yes | Yes | Yes | Production. This is the recommended option. |
nohup | Yes | No | No | Tests and temporary use. |
tmux or screen | Yes | No | No | Following the agent output interactively. |
cron with @reboot | Yes | Yes | No | Machines without systemd or without administrator access. |
In all of them the agent reads the .env file from the folder where the binary is, and needs read and write permission on that folder.
Warning
Use only one option at a time. Before switching, stop the agent that is already running so you don’t keep two processes with the same agent name.
systemd service (recommended)
As a service, the agent starts with the server, is restarted automatically if the process dies and has its logs centralized in journald.
Create the service file
Create the file /etc/systemd/system/sinfonia-agent.service with the content below, replacing <user> with the user that will run the bots:
[Unit]
Description=Sinfonia Agent
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=<user>
WorkingDirectory=/home/<user>/sinfonia
ExecStart=/home/<user>/sinfonia/agent
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.targetUser: system user that runs the agent and the bots. Avoidroot.WorkingDirectoryandExecStart: folder and full path of the agent binary.RestartandRestartSec: restart the agent 10 seconds after it exits for any reason.
Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable --now sinfonia-agentenable makes the service start on every boot, and --now starts it immediately.
Check the status and logs
systemctl status sinfonia-agent
journalctl -u sinfonia-agent -fDay-to-day commands:
| Action | Command |
|---|---|
Restart, for example after changing .env | sudo systemctl restart sinfonia-agent |
| Stop | sudo systemctl stop sinfonia-agent |
| Disable automatic start | sudo systemctl disable sinfonia-agent |
| View the last hour of logs | journalctl -u sinfonia-agent --since "1 hour ago" |
Note
A systemd service runs with a reduced PATH and without your shell configuration. If the Python or Node used by your bots was installed with tools such as pyenv or nvm, add the path in the [Service] section, for example Environment=PATH=/home/<user>/.pyenv/shims:/usr/local/bin:/usr/bin:/bin.
Important
A system service has no access to the graphical session. In it the agent operates without a graphical interface, which covers the Headless modes. For bots in Headed mode, start the agent inside the user’s graphical session, for example with nohup or tmux in a terminal of that session.
nohup
nohup keeps the agent in the background after the terminal is closed. It is the simplest option, but the agent does not come back on its own after a server reboot or a process failure.
cd /home/<user>/sinfonia
nohup ./agent > agent.log 2>&1 &To follow the output and stop the agent:
tail -f agent.log
pkill -f /home/<user>/sinfonia/agenttmux or screen
A terminal multiplexer keeps the agent in a session that stays active after you disconnect, and lets you return to it to see the output. Like nohup, it does not start with the server.
tmux new -s sinfonia
cd /home/<user>/sinfonia && ./agentPress Ctrl+B and then D to leave the session without stopping the agent. To return to it:
tmux attach -t sinfoniaWith screen, the equivalent commands are screen -S sinfonia, Ctrl+A and then D to leave, and screen -r sinfonia to return.
cron with @reboot
On machines without systemd, or when you have no administrator access, the user’s own cron can start the agent on every boot. Open the scheduler with crontab -e and add the line:
@reboot cd /home/<user>/sinfonia && nohup ./agent > agent.log 2>&1 &The agent starts on the next boot. cron does not restart the agent if the process dies.
Tip
To follow CPU, memory, real-time logs and the agent’s history, see Agents.