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.
1. Extract the packages
Section titled “1. Extract the packages”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.
2. Configure the server
Section titled “2. Configure the server”Replace the server’s config.toml with:
name = "Local development"host = "127.0.0.1"port = 27015max_players = 8
[api]enabled = falselocal_port = 27019local_state_file = ".api/local.json"
[resources]url = "http://127.0.0.1:27018/"mode = "local"path = ".resources"
[resources.pack]path = "resources/client"compression = trueencryption = false
[resources.http]enabled = truehost = "127.0.0.1"port = 27018
[scripting.js]entry = "resources/server/index.js"
[voice]enabled = truemode = "embedded"media_port = 27017This 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.
3. Start the server
Section titled “3. Start the server”Open PowerShell and run:
Set-Location C:\Revo\server.\revo-server.exeRun 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.
4. Connect to the server
Section titled “4. Connect to the server”GTA installation
Section titled “GTA installation”The helper detects GTA V Legacy through the Windows registry. Check the selected installation:
Set-Location C:\Revo\helper.\client-helper.exe gameThe result includes path and valid. If the path is missing or incorrect,
select your GTA V Legacy folder:
.\client-helper.exe game --path "D:\Games\Grand Theft Auto V"The choice is saved. Use game --path auto to restore automatic detection.
Resource storage
Section titled “Resource storage”Check whether a download location is configured:
.\client-helper.exe inspect --join-code devIf the result reports storage_required, choose a folder for resources, logs and
crash reports. This example uses C:\Revo\client-data:
.\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.
Launch GTA
Section titled “Launch GTA”.\client-helper.exe launch --join-code devThe 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.
If something goes wrong
Section titled “If something goes wrong”| 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.