Agents

This page shows how to connect an agent to a project so it can run scripts.

An agent is the process that runs your scripts. A project needs at least one online agent before anything runs. You need the Manage agents permission to add or remove agents.

Add an agent with a pair code

Use this by default. The agent connects to the server, so you do not open a port. It is the way to go on Reflex hosted by BQA.

1. Open the project, go to Agents and choose Add agent, then Pair code.
2. Enter a name. Choose how long the code stays valid (1 hour, 1 day or 7 days). Tick other projects it should serve.
3. Choose Generate pair code. Copy the command now: the code is shown once and works once.
4. Run the command on the agent host. Pick the tab that fits:
   • Docker: a docker run command. The named volume keeps the agent’s credentials across restarts.
   • Linux or Windows: download the agent jar from the same page and run the command shown. It needs Java 25.
5. The page updates by itself when the agent is online.

Give each agent its own data/ directory or Docker volume and keep it: restarts use the saved credentials.

Caution

If the page warns that the server address is localhost, an agent on another machine cannot reach it. Set auth.url in the server settings to its public or LAN address and generate a new code. See configuration.

Add an agent by URL and key

Use this when Reflex can call an agent you already run, such as the one that starts with reflex.zip.

1. Choose Add agent, then URL and key.
2. Enter a name (3 to 50 letters, numbers, - or _), the agent’s URL with its port, and its key.

The URL must work from the server, not from your browser. With the release Docker Compose use http://agent:7001. Locally use http://localhost:7001. The key is the agent’s AGENT_KEY (dev by default, so change it).

You cannot edit this kind of agent. Delete it and add it again.

Check and manage agents

The Agents list shows each agent’s status, version, platform, last seen time and projects. An agent is offline after about 45 seconds of silence.

A paired agent can serve more projects (of one owner only): open its project list on the Agents page. Remove all projects and the agent loses access.

Runs never start? See Troubleshooting.