Core SDK Overview

Reference for @outray/core, the low-level TypeScript package that powers the OutRay CLI and framework plugins.

@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

npm install @outray/core

pnpm

pnpm add @outray/core

yarn

yarn add @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

Export	Description
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.