Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/outray-tunnel/outray/llms.txt

Use this file to discover all available pages before exploring further.

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.
OptionTypeRequiredDescription
orgstringNoDefault organization slug. Individual tunnels can override this.
server_urlstringNoCustom 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).
OptionTypeRequiredDescription
protocolstringYesTunnel protocol: http, tcp, or udp.
local_portnumberYesLocal port to forward traffic to. Must be between 1 and 65535.
local_hoststringNoLocal hostname to forward to. Defaults to localhost.
subdomainstringNoRequested subdomain for HTTP tunnels (e.g. my-app → my-app.tunnel.outray.app). Not valid for TCP/UDP.
custom_domainstringNoCustom domain for HTTP tunnels. Must be configured in your OutRay dashboard. Not valid for TCP/UDP.
remote_portnumberNoRequested remote port for TCP/UDP tunnels. Randomly assigned if omitted. Not valid for HTTP.
orgstringNoOrganization 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us