Skip to content

Run locally

This walkthrough runs the server and GTA on one Windows PC, using freeroam, a JavaScript example mod. You’ll need GTA V Legacy, Rockstar Games Launcher signed in and the server runtime. The first client launch also needs internet access.

Download these archives through your developer access:

Package Archive
Windows server revo-server-<version>-release-win64.zip
Freeroam example revo-freeroam-dist.zip
Client helper client-helper-<version>-release.zip

Use folders of your choice. This guide uses C:\Revo\server for the server and C:\Revo\helper for the helper.

Extract the server and freeroam archives into the server folder. The result should include:

server/
revo-server.exe
config.toml
lib/
resources/
server/
index.js
package.json
client/
scripts/
ui/

Freeroam includes built scripts, UI and assets. Extract the helper into its own folder, keeping its lib folder beside client-helper.exe.

Replace the server’s config.toml with:

name = "Local development"
host = "127.0.0.1"
port = 27015
max_players = 8
[api]
enabled = false
local_port = 27019
local_state_file = ".api/local.json"
[resources]
url = "http://127.0.0.1:27018/"
mode = "local"
path = ".resources"
[resources.pack]
path = "resources/client"
compression = true
encryption = false
[resources.http]
enabled = true
host = "127.0.0.1"
port = 27018
[scripting.js]
entry = "resources/server/index.js"
[voice]
enabled = true
mode = "embedded"
media_port = 27017

This enables the local join code dev without a project credential. At startup, the server loads resources/server/index.js, packages resources/client into .resources and hosts the client bundle locally.

Open PowerShell and run:

Terminal window
Set-Location C:\Revo\server
.\revo-server.exe

Run it from the folder containing config.toml. Relative paths in the configuration are resolved from this directory.

After startup, the console should include:

Serving client resources on 127.0.0.1:27018/
Join code: dev. Discovery is listening on 127.0.0.1:27019.
Server is now running on port 27015.

Leave this terminal running and open another PowerShell window for the helper.

The helper detects GTA V Legacy through the Windows registry. Check the selected installation:

Terminal window
Set-Location C:\Revo\helper
.\client-helper.exe game

The result includes path and valid. If the path is missing or incorrect, select your GTA V Legacy folder:

Terminal window
.\client-helper.exe game --path "D:\Games\Grand Theft Auto V"

The choice is saved. Use game --path auto to restore automatic detection.

Check whether a download location is configured:

Terminal window
.\client-helper.exe inspect --join-code dev

If the result reports storage_required, choose a folder for resources, logs and crash reports. This example uses C:\Revo\client-data:

Terminal window
.\client-helper.exe configure --storage-dir "C:\Revo\client-data"

Keep the existing setting if storage is already configured. Client binaries are stored separately in %LOCALAPPDATA%\revo\client.

Terminal window
.\client-helper.exe launch --join-code dev

The helper downloads and verifies the matching client and resources, then starts GTA. Progress appears as JSON lines in the terminal. A launched event confirms client initialization. Joining the server and loading the world continue in GTA.

Your player should appear on Vespucci Beach. Press F1 to open freeroam’s menu.

If you change api.local_port, use dev:<port>, such as dev:27119. This is the discovery port. The helper reads the game port from the server’s response.

Next, create your first mod. Stop the server with Ctrl+C when finished. For applying changes, reading logs and testing with two clients, see Development workflow.

Issue Check
config.toml cannot be opened Start revo-server.exe from the server folder.
Missing server scripts or client resources Check that freeroam’s resources folder is directly beside revo-server.exe.
A port is already in use Check for another server instance. This setup uses UDP 27015 and 27017, and TCP 27018 and 27019.
The helper cannot resolve dev Open http://127.0.0.1:27019/local/server in a browser. It should return the join code and connection details.
Resource download fails Check that http://127.0.0.1:27018/manifest.json returns the resource manifest.
game_not_installed or invalid_game_path Check the selected GTA V Legacy installation.
server_update_required Update to a supported server version.
game_executable_running Close the running GTA clients so the helper can update their files, then launch again.

For startup errors after GTA opens, check the client log.