Config file

Use a TOML config file to define and start multiple tunnels at once.

Instead of running separate outray http, outray tcp, or outray udp commands, you can declare all your tunnels in a TOML config file and start them with a single command.

Default location

OutRay looks for a config file at outray/config.toml relative to your current working directory:

your-project/
└── outray/
    └── config.toml

Getting started

1. Create the config file

   Create outray/config.toml in your project directory. Use the example below as a starting point.

2. Validate the config

   Check your config for errors before starting:

   outray validate-config
   

   OutRay will print each tunnel it found and flag any invalid fields.

3. Start all tunnels

   Start every tunnel defined in the config file:

   outray start
   

   To use a config file at a custom path:

   outray start --config /path/to/file.toml
   

Full example

This is the complete config.toml.example from the OutRay CLI:

[global]
org = "my-team"
# server_url = "wss://api.outray.dev/"  # Optional: custom server URL

[tunnel.web]
protocol = "http"
local_port = 3000
local_host = "localhost"
subdomain = "my-app"
custom_domain = "app.example.com"

[tunnel.api]
protocol = "http"
local_port = 8000
subdomain = "api"

[tunnel.postgres]
protocol = "tcp"
local_port = 5432
local_host = "localhost"
remote_port = 20000

[tunnel.game-server]
protocol = "udp"
local_port = 5000
remote_port = 30000

[global] section

The [global] section sets defaults that apply to all tunnels.

Option	Type	Required	Description
org	string	No	Default organization slug. Individual tunnels can override this.
server_url	string	No	Custom OutRay server WebSocket URL (must start with ws:// or wss://). Defaults to wss://api.outray.dev/.

[tunnel.<name>] sections

Each tunnel is defined as [tunnel.<name>] where <name> is an identifier of your choosing (e.g. web, api, postgres).

Option	Type	Required	Description
protocol	string	Yes	Tunnel protocol: http, tcp, or udp.
local_port	number	Yes	Local port to forward traffic to. Must be between 1 and 65535.
local_host	string	No	Local hostname to forward to. Defaults to localhost.
subdomain	string	No	Requested subdomain for HTTP tunnels (e.g. my-app → my-app.tunnel.outray.app). Not valid for TCP/UDP.
custom_domain	string	No	Custom domain for HTTP tunnels. Must be configured in your OutRay dashboard. Not valid for TCP/UDP.
remote_port	number	No	Requested remote port for TCP/UDP tunnels. Randomly assigned if omitted. Not valid for HTTP.
org	string	No	Organization slug for this tunnel. Overrides the [global] org.

subdomain and custom_domain are only valid for http tunnels. remote_port is only valid for tcp and udp tunnels. OutRay will reject the config if you mix these.

Validating the config

Run outray validate-config at any time to check your config without starting any tunnels:

outray validate-config

To validate a file at a custom path:

outray validate-config --config /path/to/file.toml

Example output for a valid config:

✓ Config file is valid

Found 4 tunnel(s):

  [web]
    Protocol: http
    Local: localhost:3000
    Subdomain: my-app
    Custom Domain: app.example.com

  [api]
    Protocol: http
    Local: localhost:8000
    Subdomain: api

  [postgres]
    Protocol: tcp
    Local: localhost:5432
    Remote Port: 20000

  [game-server]
    Protocol: udp
    Local: localhost:5000
    Remote Port: 30000

Stopping all tunnels

Press Ctrl+C to stop all tunnels started from the config file. OutRay shuts down each tunnel gracefully.