Build agents

The OpsNexus agent is a small Python program you install on your own machines. It does two jobs:

• Monitoring: every 15 seconds it reports CPU, memory, disk, network, uptime and running jobs to OpsNexus.
• Building: when it has executors, it takes OpsNexus pipeline builds from the queue, checks out the code with Git, runs each step and streams the console output back. This is the same role as a Jenkins agent.

The agent only makes outbound HTTPS (or HTTP) calls to OpsNexus. OpsNexus never connects to the agent. Builds always run on your agents, never on the OpsNexus server.

Agents are managed under Build & deploy → Build agents, which has two tabs: All agents and Download & install.

#Requirements

#Registration tokens

An agent registers with a registration token.

• A token works once. After an agent registers with it, it cannot be used again.
• A token from the install page expires after 24 hours. Through the API (POST /api/agents/tokens) you can set expires_in_hours from 1 to 168.
• The token is shown once. Copy it when you create it.
• The token sets the agent's Pool (default default). The pool groups agents, for example linux-build or windows-desktop.
• The token decides whether the agent builds for This project only, or for All projects (shared). A shared agent belongs to the organization. Creating a shared token needs modify on Build agents in your organization role, and an organization admin can turn sharing off.

When the agent registers, it gets its own ID and secret. The secret is saved in the agent's config file and stored hashed in OpsNexus.

#Install an agent

1. Open Build agents → Download & install.
2. Under 1. Create a registration token, choose who the agent builds for, set the Pool, and select Create token.
3. Under 2. Run OpsNexus pipelines on it? (optional), set Executors (0 = monitoring only) and Labels.
4. Under 3. Install, choose Linux, Windows, macOS or Docker, check the OpsNexus address the agent connects to, and copy the command.
5. Run the command on the machine. The agent appears under All agents within a few seconds.

#Linux

Run as root. The installer creates the onx-agent system user and the onx-agent systemd service.

curl -fsSL https://opsnexus.example.com/api/agents/download/linux -o install.sh
sudo bash install.sh --token onx_reg_xxxxxxxx --url https://opsnexus.example.com --executors 2 --labels linux,docker,node

Workspaces are in /var/lib/opsnexus-agent/work.

#macOS

Run as an administrator. The installer creates the launchd service com.opsnexus.agent. It needs python3 (install it with xcode-select --install or Homebrew).

curl -fsSL https://opsnexus.example.com/api/agents/download/macos -o install.sh
sudo bash install.sh --token onx_reg_xxxxxxxx --url https://opsnexus.example.com --executors 2 --labels macos,xcode

The options are the same as on Linux.

#Windows

Run PowerShell as Administrator. The installer creates the scheduled task OpsNexus Agent, which runs as SYSTEM, starts at boot and restarts on failure.

Invoke-WebRequest https://opsnexus.example.com/api/agents/download/windows -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1 -Token onx_reg_xxxxxxxx -Server https://opsnexus.example.com -Executors 2 -Labels windows,dotnet

Parameters: -Token (required), -Server, -Name, -Executors, -Labels and -Insecure. Builds need Git for Windows.

#Docker

The Docker option builds the agent image from your OpsNexus server and runs it as a container. The image includes Git, bash, Python and the Docker CLI.

# 1. Build the agent image (once per machine; again after OpsNexus updates the agent)
curl -fsSL https://opsnexus.example.com/api/agents/download/docker.tar.gz -o opsnexus-agent.tar.gz
mkdir -p opsnexus-agent && tar -xzf opsnexus-agent.tar.gz -C opsnexus-agent
docker build -t opsnexus-agent opsnexus-agent

# 2. Start the agent
docker rm -f docker-agent-01 2>/dev/null || true
docker run -d \
  --name docker-agent-01 \
  --hostname docker-agent-01 \
  --restart unless-stopped \
  -e ONX_URL=https://opsnexus.example.com \
  -e ONX_REGISTRATION_TOKEN=onx_reg_xxxxxxxx \
  -e ONX_AGENT_NAME=docker-agent-01 \
  -e ONX_EXECUTORS=2 \
  -e ONX_LABELS=linux,docker \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add "$(stat -c %g /var/run/docker.sock 2>/dev/null || echo 0)" \
  -v docker-agent-01-data:/data \
  opsnexus-agent

• The registration is kept in the <name>-data volume, so the container keeps its identity when it restarts.
• Builds can use Docker mounts the host's Docker socket and adds the label docker. Builds can then run docker build, docker run and docker compose. Use a machine dedicated to builds for this.
• The page also has a Windows PowerShell variant of the commands.
• Logs: docker logs -f docker-agent-01.

Container settings:

#Next to OpsNexus with docker compose

The OpsNexus compose file has a runner service that uses the same image. On the OpsNexus server:

# in .env next to docker-compose.yml
RUNNER_TOKEN=onx_reg_xxxxxxxx
RUNNER_EXECUTORS=2
RUNNER_LABELS=linux

docker compose --profile runner up -d runner

RUNNER_NAME sets the agent name (default docker-runner). Without RUNNER_LABELS, the service uses linux,docker-runner.

#The OpsNexus address (AGENT_URL)

The agent connects to the address in its install command. That address must work from the agent machine. http://localhost:8080 and http://host.docker.internal:8080 only work on the OpsNexus server itself.

• The install page uses AGENT_URL from the server's .env. If AGENT_URL is empty, it uses PUBLIC_URL.
• If that address is local-only, the page warns you and suggests the address in your browser instead.
• You can edit OpsNexus address the agent connects to on the page for a one-off install.
• To set it for everyone, set AGENT_URL to an address every agent can reach (for example http://192.168.1.10:8080 or https://opsnexus.example.com) and restart the api service. Keep PUBLIC_URL as it is if SSO is set up, because SSO providers need that exact URL.
• Open the web port (WEB_PORT, default 8080) in the server's firewall.

# .env on the OpsNexus server
PUBLIC_URL=http://localhost:8080
AGENT_URL=http://192.168.1.10:8080

If OpsNexus moves to a new address, agents do not need to register again:

• Container: recreate it with the new -e ONX_URL=....
• Installed service: run python onx_agent.py set-url https://new-address with the agent's Python, then restart the service.

See Environment variables.

#Executors and labels

Executors is the number of builds an agent runs at the same time. 0 means monitoring only. The maximum is 32. A build that waits for an approval keeps its executor busy.

Labels let pipelines choose agents:

agent:
  labels: [linux, docker]

• An agent matches when it has every label the pipeline asks for. Matching ignores case.
• Each agent also matches its operating system (linux, windows, macos), its name and its pool, without adding them.
• Labels use letters, digits, ., _ and -, up to 40 characters. An agent can have up to 30 labels.
• A pipeline can also ask for a pool. The pool must match exactly.
• A project's agent only builds that project's pipelines. A shared agent builds any project's pipelines.

Executors and labels come from the agent's config file by default. To set them in OpsNexus instead:

1. Open Build agents → All agents and select the agent.
2. Turn on Run pipeline builds on this agent.
3. Set Executors and Labels and select Save.

The agent applies the change on its next heartbeat (within 15 seconds). Use the agent's config file goes back to the values in the config file.

#Config file

Keys you can edit:

{
  "executors": 2,
  "labels": ["linux", "docker"],
  "work_dir": "/var/lib/opsnexus-agent/work",
  "job_process_names": ["Runner.Worker"],
  "verify_tls": true
}

• job_process_names: processes that mean another CI tool is running a build on this machine, for example Runner.Worker (Azure DevOps or GitHub runner) or gitlab-runner-helper. The agent shows as busy while one runs.
• ONX_EXECUTORS, ONX_LABELS and ONX_WORK_DIR override the file.

Restart the service after editing the file.

#Agent status and actions

The All agents list shows each agent's OS, IP, status, pipelines role (executors and labels, or Monitoring only), running jobs and last heartbeat. Shared or Project shows who the agent builds for. Select an agent to see CPU, memory, disk, uptime, a CPU chart for the last hour, build statistics and actions.

Actions (need modify on Build agents; for a shared agent, at organization level):

#Upgrade an agent

• Installed service: select the agent and Upgrade, or run the installer again.
• Docker: build the image again (step 1 of the Docker command) and recreate the container. Running the Docker command again with a new token re-registers it cleanly.

#Uninstall an agent

1. Remove the service from the machine:

# Linux
sudo systemctl disable --now onx-agent && sudo rm -rf /opt/opsnexus-agent /etc/opsnexus /etc/systemd/system/onx-agent.service
# macOS
sudo launchctl bootout system /Library/LaunchDaemons/com.opsnexus.agent.plist && sudo rm -rf "/Library/Application Support/OpsNexus" /Library/LaunchDaemons/com.opsnexus.agent.plist

# Windows
Unregister-ScheduledTask -TaskName "OpsNexus Agent" -Confirm:$false; Remove-Item -Recurse "$env:ProgramFiles\OpsNexus", "$env:ProgramData\OpsNexus"

For a container: docker rm -f <name>.

2. In OpsNexus, select the agent and Unregister so its secret stops working.

#Run the agent by hand

python onx_agent.py register --url https://opsnexus.example.com --token onx_reg_xxxxxxxx --name build-01 --executors 2 --labels linux
python onx_agent.py run

Commands: register, run, start (containers: register from ONX_* variables if needed, then run), set-url <url> and version. Set ONX_AGENT_CONFIG=/path/agent.json to use another config file.

#Troubleshooting

For more, see Troubleshooting.