Networking

Rivet provides a simple yet powerful networking system for your actors. When you create an actor, you define the ports it will use, and Rivet handles the networking infrastructure, including URL generation, port mapping, and traffic routing.

Configuring Networking

When creating an actor, you specify the ports that your application needs to expose. This is done through the network.ports parameter when creating your actor with the actor.create API:

// Simple example defining an HTTP port
const actor = await rivet.actors.create({
  // ...other configuration
  network: {
    ports: {
      http: { protocol: "https" }
    }
  }
});

Once your actor is running with properly configured ports, you can access it through the URLs provided by Rivet. These URLs are available:

• Via the API in the actor creation response under actor.network.ports.http.url
• In the Rivet Hub dashboard for your actor

Listening For Requests On The Actor

Once your actor is running, Rivet injects environment variables containing information about the assigned ports. Your application should use these variables to determine what port to listen on.

For example:

// Simple example starting an HTTP server
const express = require('express');
const app = express();
const port = process.env.PORT_HTTP;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

Environment Variable Naming

For each port defined in your actor configuration under network.ports, Rivet sets a single environment variable PORT_{NAME} where {NAME} is the uppercase version of the key you used in the network.ports object.

Your application should read these environment variables to know which ports to bind to.

For example:

• network.ports.http becomes the PORT_HTTP environment variable
• network.ports.game becomes the PORT_GAME environment variable
• network.ports["hello-world"] becomes the PORT_HELLO_WORLD environment variable

Examples

Here are complete examples demonstrating how to set up networking for both the client and server.

HTTP Server Example

Client (Creating the Actor)

// Creating an actor with an HTTP port
const actor = await rivet.actors.create({
  tags: { name: "my-http-server" },
  buildTags: { name: "my-http-server", current: "true" },
  network: {
    ports: {
      // "http" is the port name (becomes PORT_HTTP env var)
      http: { protocol: "https" }
    }
  },
});

console.log(actor.network.ports.http); // Information about HTTP port
console.log(actor.network.ports.http.url); // URL to connect to

Actor (Starting the Server)

const express = require('express');
const app = express();

// Get the port from the environment variable
const port = process.env.PORT_HTTP;

app.get('/', (req, res) => {
  res.send('Hello from Rivet!');
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

TCP Game Server Example

Client (Creating the Actor)

// Creating an actor with a TCP port for a game server
const actor = await rivet.actors.create({
  tags: { name: "my-game-server" },
  buildTags: { name: "my-game-server", current: "true" },
  network: {
    ports: {
      // "game" is the port name (becomes PORT_GAME env var)
      game: { protocol: "tcp" }
    }
  },
});

let port = actor.network.ports.game;
console.log(`${port.hostname}:${port.port}`); // Connection address for port

Server (Starting the Server)

const net = require('net');

// Get the port from the environment variable
// This corresponds to the "game" key in the network.ports object
const port = process.env.PORT_GAME;

const server = net.createServer((socket) => {
  socket.write('Hello from Rivet Game Server!\r\n');
});

server.listen(port, () => {
  console.log(`TCP game server running on port ${port}`);
});

Supported Protocols

Rivet supports the following protocols for actor ports:

SSL and TLS

When you use the https or tcp_tls protocols, Rivet automatically handles all SSL/TLS encryption for you.

Your server should listen for regular unencrypted HTTP or TCP traffic on the assigned port.

Troubleshooting

Bad Gateway (502)

If you receive a "Bad Gateway" (502) error when accessing your actor, it typically means:

• Your actor is listening on the wrong port (check the environment variables)
• Your actor has crashed during request handling

Resolution: Check the actor logs in the Rivet Hub dashboard to see if your server started correctly. Verify that your application is listening on the port specified by the PORT_{NAME} environment variable, not a hardcoded port.

Not Found (404)

A "Not Found" (404) error usually indicates:

• Your actor has crashed before receiving the request
• The URL you're using is incorrect
• There's a bug in your application's routing

Resolution: Manually validate the URL shown for the actor in the Rivet Hub dashboard. Check the actor logs to ensure your application started successfully and is handling requests properly.