Agents

An agent is the component that actually executes your processes. By default, Runeya automatically starts a local agent.

Agent Role

The Runeya server delegates process execution to an agent:

Server ──HTTP/Bearer──► Agent ──execa──► Your process

The agent is stateless: it persists nothing to disk. All configuration is managed by the server.

Local Agent (automatic)

On startup, Runeya automatically launches a local agent on localhost:9546. All your services are assigned to it by default.

No configuration needed for the standard case.

Remote Agents (future)

Agents on other machines will be supported in a future version, allowing control of remote processes from the central interface.

Security

• The agent generates a random passphrase (32 bytes) on startup
• All server → agent requests must include Authorization: Bearer <passphrase>
• The agent only binds to 127.0.0.1 by default
• The passphrase is stored encrypted in agents.json

Lazy Deployment

The server does not push service configurations to the agent on startup. A service is only deployed to the agent when it is started for the first time. This avoids unnecessary work for services that are never launched.

Agent Health

The interface shows the connection status of each agent in real-time via WebSocket. A colored indicator shows whether the agent is responding correctly.