Agents

An agent runs your services' processes. The server decides what should run, and the agent starts the processes on its machine. A service can therefore run on a different machine from the one where you use the UI.

The local agent

Runeya starts an agent on your machine at launch. It shows with the "Local" tag in the agent list. It cannot be edited or removed. Without any other setting, your services run on it.

Adding an agent on another machine

1. Start the agent on the remote machine

The remote machine needs Node.js 22 or later, and Runeya:

npm install -g @runeya/runeya
runeya --agent --lan

--lan makes the agent listen on all network interfaces. Without it, the agent only listens on 127.0.0.1 and cannot be reached from another machine.

Flag	Variable	Default
--agent	none	runs the agent alone, without server or UI
--lan	none	listens on all interfaces (0.0.0.0)
--host <address> or --agent-host <address>	RUNEYA_AGENT_HOST	127.0.0.1
--port <n> or --agent-port <n>	RUNEYA_AGENT_PORT	4001

At startup, the agent prints two lines to note down:

RUNEYA_PASSPHRASE=<64 hexadecimal characters>
Agent listening on 0.0.0.0:4001

The passphrase changes every time the agent restarts. To keep it fixed, start the agent with the RUNEYA_AGENT_PASSPHRASE variable (a hexadecimal string of your choice). Otherwise, you have to enter the new passphrase in Runeya after each restart.

2. Register the agent in Runeya

1. Open Settings → Agents (in the "Access and integrations" group).
2. Click Register Agent.
3. Fill in the form:
   • Name: a name to recognize the machine, for example staging-server.
   • URL: the agent's address, for example http://192.168.1.20:4001.
   • Passphrase: the value printed after RUNEYA_PASSPHRASE=.
   • Belongs to: shown only if this computer syncs an organization. Pick "This machine" or the organization that may use the agent.
4. Click Test Connection. The "Connected" tag confirms the agent answers. On failure, the red tag shows the error.
5. Click Register Agent.

The agent shows in the list with its status, "Connected" or "Disconnected". The actions on each row let you edit it, remove it, set the variables it passes through ("Env passthrough") and its Traefik proxy. When editing, leave the passphrase empty to keep the saved value.

Choosing a service's agent

A service runs on the agent picked in this order:

1. the service's own agent, if it has one;
2. otherwise, the active environment's default agent;
3. otherwise, the local agent.

When creating a service, the Agent field offers "— Inherit from active environment —" by default. Pick an agent to force the machine.

For an existing service, open the Config tab, then Commands. The Agent card lets you change machine, and the change is saved right away. If the service was running, Runeya stops it on the old agent. Then click Start to run it on the new one.

For a whole environment, open the environment form and set Default agent. Services without an explicit agent run on that agent while the environment is active. For example, the staging environment can send every service to the staging machine.

What the agent's machine needs

The service's commands run on the agent's machine. The project's code and the tools it needs (Node, Docker, database…) must therefore be there.

• The working directory is resolved on the agent's machine. If the expected folder does not exist and the service has a git repository configured, Runeya can offer to clone it.
• The agent machine's environment variables are not passed to services, except those declared in Env passthrough.
• The agent stores nothing on its disk. It receives the service's configuration from the server at each start. There is nothing to back up on an execution machine.

If the agent cannot be reached, the service does not start. A "Start failed" notification says the agent is not responding, and the agent shows as "Disconnected" in Settings → Agents. Check that runeya --agent is still running on the remote machine and that the saved passphrase is correct.

Security

By default, an agent only listens on 127.0.0.1. It only accepts requests that carry its passphrase. Runeya stores that passphrase encrypted.

An agent started with --lan or --host 0.0.0.0 can be reached by any machine on the network. Only the passphrase protects it then. Keep this mode for a trusted network.