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.

@outray/core is the foundational package for OutRay. It provides the WebSocket tunnel client, mDNS local-access utilities, and the binary message protocol used between the client and server. The CLI and all official framework plugins are built on top of it.

​
When to use @outray/core

CLI

Use outray (the CLI) when you want to start tunnels from the command line without writing code.

Framework plugins

Use @outray/vite or another framework plugin when you want tunnels to start automatically as part of your dev-server setup.

@outray/core

Use @outray/core directly when you are building a framework plugin, a custom integration, or need programmatic control over the tunnel lifecycle.

​
Installation

npm install @outray/core

​
Quick start

import { OutrayClient } from '@outray/core';

const client = new OutrayClient({
  localPort: 3000,

  // Optional: API key for authentication
  apiKey: process.env.OUTRAY_API_KEY,

  // Optional: request a specific subdomain
  subdomain: 'my-app',

  onTunnelReady: (url) => {
    console.log(`Tunnel ready at: ${url}`);
  },

  onError: (error, code) => {
    console.error(`[${code}] ${error.message}`);
  },

  onRequest: (info) => {
    console.log(`${info.method} ${info.path} → ${info.statusCode} (${info.duration}ms)`);
  },

  onReconnecting: (attempt, delay) => {
    console.log(`Reconnecting in ${delay}ms (attempt ${attempt})`);
  },
});

client.start();

// Later, when you want to stop:
client.stop();

​
Exports

​
Classes

OutrayClient

The primary tunnel client. Connects to the OutRay server over WebSocket and proxies HTTP, TCP, and UDP traffic to a local port. See OutrayClient options for the full API.

MDNSAdvertiser

Advertises a service on the local network via mDNS so devices on the same LAN can reach <name>.local.

LocalProxy

HTTP reverse proxy that binds to port 80 on the local machine and forwards requests to a local service port.

LocalHttpsProxy

HTTPS reverse proxy that binds to port 443 on the local machine. Uses a self-signed certificate by default; trusts system certificates if available.

LocalAccessManager

Convenience class that combines MDNSAdvertiser, LocalProxy, and LocalHttpsProxy for managing full local access.

​
Protocol utilities

ExportDescription
encodeMessage(msg)Serialize a ClientMessage or ServerMessage to a string for transmission over the WebSocket.
decodeMessage(raw)Parse a raw WebSocket message string into a typed ServerMessage or ClientMessage.

​
Exported types

// Client configuration
OutrayClientOptions
RequestInfo
TunnelProtocol            // "http" | "tcp" | "udp"

// Protocol messages — client → server
ClientMessage
OpenTunnelMessage
TunnelResponseMessage
TCPDataMessage
TCPCloseMessage
UDPResponseMessage
WSUpgradeResponseMessage
WSFrameMessage
WSCloseMessage

// Protocol messages — server → client
ServerMessage
TunnelOpenedMessage
TunnelDataMessage
TCPConnectionMessage
TCPIncomingDataMessage
TCPIncomingCloseMessage
UDPDataMessage
ErrorMessage
WSUpgradeMessage

// Error codes
ErrorCode
ErrorCodes                // const object with all error code strings

// Local access
LocalAccessInfo

​
Building a framework plugin

@outray/core is designed to be embedded inside framework-specific wrappers. A minimal plugin looks like this: 
import { OutrayClient, type OutrayClientOptions } from '@outray/core';

export function myFrameworkPlugin(options: { apiKey?: string }) {
  let client: OutrayClient | null = null;

  return {
    onServerStart(port: number) {
      client = new OutrayClient({
        localPort: port,
        apiKey: options.apiKey,
        onTunnelReady: (url) => {
          console.log(`\n  Tunnel: ${url}\n`);
        },
        onError: (error, code) => {
          console.error(`OutRay error [${code}]: ${error.message}`);
        },
      });

      client.start();
    },

    onServerStop() {
      client?.stop();
    },
  };
}

​
Error codes

import { ErrorCodes } from '@outray/core';

// Available values:
ErrorCodes.SUBDOMAIN_IN_USE           // Requested subdomain is already taken
ErrorCodes.AUTH_FAILED                // Invalid or expired API key
ErrorCodes.LIMIT_EXCEEDED             // Account tunnel limit reached
ErrorCodes.INVALID_SUBDOMAIN          // Subdomain contains invalid characters
ErrorCodes.CUSTOM_DOMAIN_NOT_CONFIGURED // Domain not set up in the dashboard
See Protocol Reference for the full list of error codes and when each one is returned.

Build docs developers (and LLMs) love

Get started for freeTalk to us