Node SDK

The Node SDK opens tunnels from code — useful for test harnesses, preview environments, and scripts that need a public URL on demand. It vendors the same client the CLI uses.

Install

npm install @omsapi/osmrouter

On install it downloads the client binary for your platform. Set OSM_TOKEN in the environment, or pass token explicitly.

Open a tunnel

tunnel.ts

import { connect } from "@omsapi/osmrouter";

const tunnel = await connect({
	port: 8080,
	token: process.env.OSM_TOKEN,
});

console.log(`Public URL: ${tunnel.url}`);

Pin a subdomain

const tunnel = await connect({
	port: 8080,
	subdomain: "my-app", // -> https://my-app.osmrouter.com
});

Close a tunnel

await tunnel.close();

The tunnel stays up for the life of the process unless you close it. In a test suite, open in beforeAll and close in afterAll.

Options

Option	Type	Default	Description
`port`	`number`	—	Required. Local port to expose.
`token`	`string`	`process.env.OSM_TOKEN`	Agent token.
`subdomain`	`string`	random	Pin a stable subdomain.
`domain`	`string`	`osmrouter.com`	Verified custom domain to serve under.
`relay`	`string`	`tunnel.osmrouter.com:8443`	Advanced. Self-hosted relay endpoint.

Example: a public URL for a test

webhook.test.ts

import { connect } from "@omsapi/osmrouter";
import { afterAll, beforeAll, expect, test } from "vitest";

let tunnel: Awaited<ReturnType<typeof connect>>;

beforeAll(async () => {
	tunnel = await connect({ port: 3000, subdomain: "ci-webhooks" });
});

afterAll(async () => {
	await tunnel.close();
});

test("provider can reach our webhook", async () => {
	const res = await fetch(`${tunnel.url}/health`);
	expect(res.status).toBe(200);
});

Pass the token from the environment, not a hard-coded string. Anyone with it can open tunnels on your account.

Next steps

CLI reference — the same options as environment variables.
REST API — manage tunnels, domains, and usage over HTTP.