How To Create an alt:V Server (2025 Quickstart Guide)

Want to host your own GTA V multiplayer world with alt:V? This guide shows you two reliable setup paths (Windows & Linux), gives you a clean server.toml, a first working JavaScript resource, firewall/ports, and optional systemd service so you can go from zero to a public, masterlisted server fast.

---

What you’ll need

• A legitimate copy of GTA V (players need this; the server does not).
• Windows 10/11 or Ubuntu 22.04+ (or any recent x64 Linux).
• Basic terminal/PowerShell skills.

alt:V servers are standalone; you don’t install GTA on the server.

---

Folder layout (we’ll create this)

altv-server/
├─ altv-server.exe (Windows) or altv-server (Linux)
├─ libnode.dll / libnode.so
├─ server.toml
├─ package.json  ← sets ESM (type: module) for JS resources
└─ resources/
   └─ example/
      ├─ resource.toml
      ├─ server.mjs
      └─ client/
         └─ client.mjs

---

Option A — Quickstart (Windows & Linux) with altv-pkg

This pulls the latest official binaries for you.

1. Create a working directory

mkdir altv-server && cd altv-server

2. Initialize Node (for tooling only)

npm init -y
npm i --save-dev altv-pkg

3. Download server binaries

npx altv-pkg release

Re-run npx altv-pkg release any time you want to update.

---

Option B — Manual install

1. Download the Server build from the official alt:V downloads page (choose Windows or Linux).
2. Extract into altv-server/.

---

Create package.json (top-level)

This enables ESM syntax (import ...) for your JS resources.

{
  "name": "altv-server",
  "private": true,
  "type": "module"
}

---

Minimal server.toml

Create server.toml in the server root:

# Displayed name in the alt:V client
name = "My alt:V Server"
# Bind to all interfaces
host = "0.0.0.0"
# Default game port (TCP & UDP)
port = 7788
# Player slots
players = 128
# Show on masterlist? (set true for public)
announce = true
# Obtain a token from the alt:V dashboard and paste here when going public
# token = "YOUR_MASTERLIST_TOKEN"

# Load the JS module and our example resource
modules = ["js-module"]
resources = ["example"]

# Helpful in development
debug = true
logStreams = ["console", "file"]

Tip: Ports when using external voice are typically 7798 (server) and 7799 (client); open them only if you run the voice server separately. The basic in-process voice needs only your game port.

---

Your first resource (JavaScript)

Create resources/example/resource.toml:

# Server-side language for this resource
type = "js"
# Client-side language for this resource
client-type = "js"

# Entry files
main = "server.mjs"
client-main = "client/client.mjs"

# Files the client may download
client-files = [
  "client/*",
]

resources/example/server.mjs

import * as alt from 'alt-server';

alt.on('playerConnect', (player) => {
  alt.log(`+ ${player.name} connected`);
  player.emit('welcome:notify', `Welcome to ${alt.getServerConfig().name}!`);
});

alt.on('playerDisconnect', (player, reason) => {
  alt.log(`- ${player?.name ?? 'unknown'} left (${reason})`);
});

resources/example/client/client.mjs

import * as alt from 'alt-client';

alt.onServer('welcome:notify', (msg) => {
  alt.log(`Server says: ${msg}`);
  // Simple on-screen help text
  alt.everyTick(() => {
    alt.drawText2d(msg, 0.5, 0.9, 0.5, 255, 255, 255, 255, 0, true, true, 0);
  });
  // Remove after ~8 seconds
  alt.setTimeout(() => alt.clearEveryTick(), 8000);
});

That’s a complete resource. When a player connects they receive a welcome text.

---

Start the server

Windows (PowerShell)

cd C:\path\to\altv-server
./altv-server.exe

Linux

cd /opt/altv-server   # or your path
chmod +x altv-server
./altv-server

If startup is clean, you’ll see logs and the server will be reachable at your.ip:7788. Join via the alt:V client (Direct Connect) or from the Masterlist (if announce = true and a valid token is set).

---

Open the firewall

Windows (PowerShell, run as Admin)

New-NetFirewallRule -DisplayName "altV 7788 TCP" -Direction Inbound -Protocol TCP -LocalPort 7788 -Action Allow
New-NetFirewallRule -DisplayName "altV 7788 UDP" -Direction Inbound -Protocol UDP -LocalPort 7788 -Action Allow

Linux (UFW)

sudo ufw allow 7788/tcp
sudo ufw allow 7788/udp

If using an external voice server, also allow 7798/udp and 7799/udp.

---

(Optional) Run alt:V as a service on Linux

Create /etc/systemd/system/altv.service:

[Unit]
Description=alt:V Server
After=network.target

[Service]
User=altv
WorkingDirectory=/opt/altv-server
ExecStart=/opt/altv-server/altv-server --port 7788
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now altv
journalctl -u altv -f

---

Quality-of-life for development

• Debug mode: keep debug = true while building; toggle off for production.
• Node inspector (server JS): add this to resources/example/resource.toml if you need server-side debugging: [js-module] inspector = true Then attach Chrome DevTools → Node target.
• TypeScript: add a tsconfig.json, compile to dist/, and point main/client-main to compiled files. Install types: npm i -D @altv/types-server @altv/types-client.

---

Updating & backups

• Update binaries: rerun npx altv-pkg release (Option A) or re-download the ZIP (Option B).
• Backups: zip resources/, server.toml, and any database/external configs. Automate with a cron or scheduled task.

---

Production hardening checklist

• Set a strong token and announce = true for the masterlist.
• Keep debug = false in production.
• Use logStreams = ["file"] in prod and rotate logs externally if needed.
• Only expose needed ports (7788; 7798/7799 if external voice).
• Consider useCdn = true for large downloads; generate packages with --justpack and serve via HTTPS.
• Monitor with a watchdog (systemd Restart=on-failure) and set up alerts.

---

Troubleshooting (fast fixes)

• Can’t see server on the list: ensure announce = true, valid token, open 7788 TCP/UDP on host and router/NAT; wait a few minutes for propagation.
• Clients stuck on download: if you added big assets, consider useCdn = true and packaging (--justpack).
• Ports already in use: pick a different port in server.toml or stop the conflicting service.
• Nothing happens on connect: confirm resource names match resources = ["example"] and your folder lives under resources/example.

---

FAQ – alt:V Servers

Do I need GTA V installed on the server machine?
No. Only players need a legitimate GTA V copy. The server itself runs without the game installed.

Which operating systems are supported for hosting alt:V?
Windows 10/11 and modern Linux distributions (Ubuntu 22.04+ or any recent x64 Linux) are supported.

What ports must be open for alt:V to work?
By default, TCP/UDP port 7788 must be open. If you run an external voice server, also open 7798/UDP and 7799/UDP.

Why doesn’t my server show up in the masterlist?
Make sure you set announce = true, added a valid masterlist token, and allowed 7788 TCP/UDP through your firewall and router. It may take a few minutes for the listing to propagate.

How do I update the server binaries?
If you installed via altv-pkg, simply run:

npx altv-pkg release

If you installed manually, download the latest build from the official alt:V download page.

Can I run the server as a background service?
Yes. On Linux, you can set up a systemd service (altv.service) to start automatically and restart on failure.

How do I make my server more secure for production?

• Disable debug mode.
• Set logStreams = ["file"].
• Use a strong masterlist token.
• Expose only required ports.
• Automate backups for resources and configs.

Where can I find more resources for my server?
The official alt:V Hub and community GitHub repositories contain many example resources. You can also check guides on FiveMX for optimization and server growth.

---

Where to go next

• Add more resources from the community Hub and example repositories.
• Set up a voice server externally for big populations.
• Automate CI/CD to push updates to your box.

Recommended reads (on FiveMX)

• Compare frameworks: FiveM vs RAGE:MP vs alt:V — Which one should you pick?
• Grow your community: How to advertise your server (works for any GTA V MP)
• Build your home base: How to create a website for your gaming server
• Tuning tips: Performance & Optimization

---

Copy‑paste snippets (quick reference)

Windows start:

./altv-server.exe

Linux start:

./altv-server

Open ports (Windows):

New-NetFirewallRule -DisplayName "altV 7788 TCP" -Direction Inbound -Protocol TCP -LocalPort 7788 -Action Allow
New-NetFirewallRule -DisplayName "altV 7788 UDP" -Direction Inbound -Protocol UDP -LocalPort 7788 -Action Allow

Open ports (Linux):

sudo ufw allow 7788/tcp && sudo ufw allow 7788/udp

You’re set. Spin it up, connect from the alt:V client, and start building resources!