Skip to content

Server agent and optional API ​

The agent is the private bridge between the web application and the game host. It can create the game process, stop it, send console commands, stream logs, manage the engine ban file and transfer approved model files.

Configure the agent ​

Inside web-platform/samp-agent/, copy .env.example to .env. Generate a fresh random SAMP_AGENT_KEY and set the absolute game directory and executable:

sh
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Use the complete agent example. On Windows use a forward-slash path such as F:/Servers/OpenRP-Framework and ./omp-server.exe; on Linux use /opt/openrp-framework and ./omp-server.

sh
npm ci
npm run check
npm test
npm start

node-pty is native. Install the appropriate C++ build tools if npm cannot obtain a suitable prebuilt dependency. Do not copy a Windows node_modules directory to Linux.

Connect the web app ​

Set SAMP_AGENT_URL in the web environment to the agent’s private HTTP origin, normally http://127.0.0.1:7001 for standalone hosting. Set the same SAMP_AGENT_KEY in both processes. Restart them after configuration changes.

The browser calls authenticated Next.js /api/samp/* routes. Those routes enforce staff levels and add the agent key server-side. The key must never be bundled into client code or put into a public URL.

Process ownership ​

The agent reports the process it spawned, not every omp-server running on the host. Stop a manually started game before using ACP Start. Put the agent and game in the same process namespace when containerising them.

The agent does not automatically start a game when the agent itself starts. Use ACP Start or a deliberately configured operational procedure. Keep one agent and one game instance per configured directory/port.

Console and logs ​

With a configured RCON password, Stop attempts a graceful RCON exit. Without one it writes exit to its owned PTY. A delayed termination fallback exists. Match SAMP_RCON_PASSWORD with the game’s RCON configuration if you enable it.

The agent reads log.txt and streams process output. It also reads/writes root bans.json, distinct from account bans in MariaDB. Its model endpoints are restricted to paths below the game’s model directory.

Optional Fastify API ​

web-platform/api/ currently provides GET /health, not a replacement account API or the ACP control bridge. To run it, copy its .env.example to .env, set PORT and WEB_URL, then:

sh
npm ci
npm run build
npm start

It listens on port 3001 by default. Leave it private or omit it unless extending that service. CORS origin configuration is not authentication; add authenticated, validated endpoints if you build on the scaffold.

Open-source roleplay foundations for open.mp. Bring your own world.