JavaScript embed
Installation · Integration · Sockets · Messages · Provider · Embed
This Node 24 console app embeds URnetwork in your product on Windows, macOS and Linux. It obtains this installation's scoped client JWT from your backend, starts the embedded device and shows its status and its own data caps, following the embed contract. The device carries only the traffic the app sends through it: it uses no VPN API. The JavaScript SDK cannot run a local Device, so the app starts the native companion in embed mode as its child process: the companion owns the device and the installation state and serves the status on a loopback route.
Files
| File | Purpose |
|---|---|
| main.mjs, command.mjs | Commands and exit codes. |
| token.mjs | fetchClientJwt: the one place the app obtains its client JWT. Replace it with your own sign-in. |
| session.mjs | The run: settings, the installation's identity, the companion child process, the status loop and the cap reads. |
| companion.mjs | Starting, reading and stopping the native companion in embed mode. |
| caps.mjs | The app's own data caps, read with its client JWT. |
| status.mjs | The status rules, the data fields and the status line. |
| state.mjs | The private installation state directory. |
| selftest.mjs, embed.test.mjs | The credential-free self-test; npm test runs it and also tests the exit codes, the companion child process and whole runs against stand-ins. |
| server/embed-server.mjs | The backend tool: provision, caps, usage, removal. Server only. |
| ../integration/companion/ | The native companion (Go) that owns the embedded device. |
Build and self-test
Use Node 24 or later and Go 1.27.4. Neither the app nor the backend tool needs packages; the app needs the native companion built. The companion's go.mod pins a released SDK version; upgrade from the companion directory with go get github.com/, which needs network access. The embed app needs an SDK release from the first release after sdk c638dfa8. From examples/ on macOS or Linux:
cd integration/companion
go mod tidy
go test .
go build -o bin/ur-companion .
cd ../../embed
npm test
node main.mjs --self-test
node main.mjs --licenses > licenses.json
node main.mjs --version
node server/embed-server.mjs --self-testOn Windows, in PowerShell from examples\javascript:
cd integration\companion
go mod tidy
go test .
go build -o bin\ur-companion.exe .
cd ..\..\embed
npm test
node main.mjs --self-test
node main.mjs --licenses > licenses.json
node main.mjs --version
node server\embed-server.mjs --self-testThe app runs the companion from .. (ur-companion.exe on Windows); set URNETWORK_ to its absolute path to use another one. The companion is pure Go, so any host builds every desktop target, for example GOOS=windows GOARCH=amd64 go build -o bin/.
--self-test needs no credentials, no network and no companion. It checks the contract's byte, reset time, client limit and status line vectors, the status rules and their order, the data fields, the cap object parsing, the JWT client_id claim, the token fetch against a stand-in token server on loopback, the state directory, the configuration errors and the start line. --licenses prints the SDK's licenses and data attributions as a JSON array, from the companion's --licenses, to publish with your app. npm test runs the same checks, plus the exit codes, the companion child process and two whole runs against a stand-in companion script, token server and cap API (macOS and Linux). The backend tool's --self-test checks the contract's backend rules against a scripted API and a loopback stand-in.
Backend
Only your backend holds the root credential, URNETWORK_. For production make it an API key (POST /account/): it authenticates as your network exactly like a network JWT, with the same full scope, and you rotate it by creating a new key, deploying it and removing the old one. Treat it like a production database password. Your backend provisions one client per running installation, keyed user:, because the platform keeps one resident connection per client (contract).
With the token server. The Go token server is the reference backend: the app posts its instance-id with a demo session token, and the server provisions or reissues the installation's client, puts new clients in their ACL group (isolated unless URNETWORK_ is default), applies default caps to them and answers the client JWT (HTTP contract). The app fetches on every start.
With the backend tool. server/ runs the same steps from your own backend, with the integration allocator's settings, map and lock (URNETWORK_, URNETWORK_, optional URNETWORK_). Keep its map separate from the token server's. On macOS or Linux:
export URNETWORK_ ROOT_ JWT= 'urn_ ...' # from your secret store
export URNETWORK_ CLIENT_ MAP= /srv/ myservice/ urnetwork/ clients.json
export URNETWORK_ DEFAULT_ ACL_ GROUP= isolated # the default; default for an app that uses Messages
KEY= user: alice: 22222222-2222-2222-2222-222222222222
node server/embed-server.mjs provision "$KEY" /path/to/state/client.jwt # prints {"client_ id": "... "}
node server/embed-server.mjs cap "$KEY" --monthly 10000000000 # 10 GB a month
node server/embed-server.mjs cap "$KEY" --total null --reset-total # clear the total cap
node server/embed-server.mjs usage "$KEY"
node server/embed-server.mjs usage-all # one cap object per line
node server/embed-server.mjs acl "$KEY" default # move it to the default ACL group
node server/embed-server.mjs status # the network's Embed state
node server/embed-server.mjs cap "$KEY" --monthly 0 # pause the installation
node server/embed-server.mjs remove "$KEY"The curl equivalents are in the contract: provision, caps. Caps merge: an omitted option keeps its cap, null clears it. The monthly cap resets at 00:00 UTC on the first of the month; the running total only when you reset it. Usage is accounted when contracts settle, so a client can pass a cap by up to its open contracts. A cap of 0 pauses the installation until that cap changes; remove deactivates its client, which loses access at its next reconnect. New clients go into the ACL group that URNETWORK_ names: isolated when it is unset, so your users never see each other in your network's peer list, or default for an app that uses Messages. provision saves a new client's mapping with a pending_acl record, applies the group with POST /network/, and only then writes the client JWT; after a failure the record stays and the next provision applies the group. acl <key> default or acl <key> isolated moves a client later and prints {"client_. cap, usage, remove and acl exit 78 with no client is mapped for that key; run provision first for a key without a client, and a held map lock exits 1. On a server that predates a route the tool exits 1 with /network/, or <path> answered 404: the server predates the data-cap routes for the cap routes; set URNETWORK_ to provision on a server without ACL groups (contract). status prints your network's Embed state from GET /network/ as one line, embed enabled: yes | client limit: 5000 | active clients: 1234. Until the URnetwork team enables Embed for your network (an Embed plan), cap, usage, usage-all and acl exit 78 with embed not enabled: Embed isn't enabled for this network; see https://, and provision still writes the client JWT but keeps the default ACL group in pending_acl and prints embed not enabled: the client's defaults stay pending until Embed is enabled; see https:// on stderr; the next provision after Embed is enabled applies it (contract).
The client limit. A network can have 100 active top-level clients by default; provider installs and child clients never count, and a client stops counting when it is removed or after 30 days without connecting. Provisioning past the limit is refused, and the tool prints client limit reached: your network is at its client limit; see https:// and exits with 78. An Embed plan raises your network's limit: request one on the Services page.
Package
Ship the native companion with your app, one binary per OS and architecture, for example bin/, bin/ and bin/, and point URNETWORK_ at the right one. The app itself needs no URnetwork JavaScript package. The SDK and connect are licensed under the Mozilla Public License 2.0: your app's own code can stay proprietary, and changes to the SDK's own files are shared under the MPL. Publish the SDK's licenses and data attributions with your app: the companion's /embed-status returns them for the host OS (GetLicenses). The embedded device needs no VPN entitlement, but your privacy policy and store privacy details must say that the app routes some of its users' traffic through URnetwork.
client.jwt lives in the installation's private state directory, protected by the operating system's user isolation. A production app may also encrypt it with the platform's secret store (the Keychain, DPAPI or libsecret). Either way it is a bearer secret: never print, log or back it up.
Configure the installation
Create a private state directory once, and keep it for the life of the installation:
mkdir -p ~/ .local/ state/ my-app/ embed && chmod 700 ~/ .local/ state/ my-app/ embed # Linux
mkdir -p ~/Library/Application\ Support/MyApp/embed && chmod 700 ~/Library/Application\ Support/MyApp/embed # macOSNew-Item -ItemType Directory -Force "$env: LOCALAPPDATA\MyApp\embed" # WindowsThen either configure the token server, which the app calls on every start:
export URNETWORK_ EMBED_ STATE_ DIR= "$HOME/ .local/ state/ my-app/ embed"
export URNETWORK_ TOKEN_ SERVER_ URL= http:// 127.0.0.1: 8790 # an HTTPS origin in production
export URNETWORK_ DEMO_ SESSION= 'a-demo-session-token-from-the-token-servers-session-file'or write client.jwt into the state directory with the backend tool's provision and set only URNETWORK_. The app creates instance-id on first run; with the token server, that is the installation ID it sends. URNETWORK_ (default https://) is the API of the app's own cap reads.
Run
node main.mjsnode main.mjsThe app prints the client ID and installation ID, then a status line when any field changes, and otherwise once a minute:
embed client 11111111-1111-1111-1111-111111111111, installation 22222222-2222-2222-2222-222222222222
status: connecting | data this month: checking | data total: checking
status: connected | data this month: 1.2 GB of 10.0 GB | data total: no cap| Field | Shows |
|---|---|
| Status | client limit, retry at HH:MM UTC, paused, data cap reached, resets YYYY-MM-DD HH:MM UTC, data cap reached, connected or connecting: the first that applies (rules). |
| Data this month | checking, unavailable, no cap, or the bytes used this UTC month of the monthly cap. While Embed isn't enabled for your network, the cap read answers Embed isn't enabled for this network. and both data fields read unavailable (contract). |
| Data total | The same for the running-total cap. |
client limit means the platform holds this client off for your network's concurrent client limit; the SDK retries by itself at the time shown. data cap reached means a cap is reached: the device gets no new data until the month rolls over, or until your backend raises, clears or resets the cap. Ctrl-C stops the app. Exit codes: 0 after a requested stop, 78 for a configuration or credential problem that a restart does not fix (missing or invalid state, a network JWT, an auth logout, or a token server answer of 401 or 409), and 1 for any other failure, including any other token server answer. The commands are run (the default), --self-test, --licenses and --version; any other argument is a usage error (78).
Next
The embed example ends where the app's own traffic begins (contract). The installation's state works with the other examples: export URNETWORK_ as the content of client.jwt and URNETWORK_ as the content of instance-id, and run one program at a time with one identity.
- Sockets: the JavaScript Sockets examples use a hosted Device today.
- Messages: the Messages examples run the native companion in its messaging mode with that identity. That companion's Device provides to your network, unlike the embed Device, so ask your users first, and the client must be in the
defaultACL group (provision withURNETWORK_, or move it with the backend tool'sDEFAULT_ ACL_ GROUP= default acl <key> default). Anisolatedclient, the examples' default, never appears in your network's peer list.