@thenewlabs/locus-server

One command stands up a complete, self-contained Locus deployment: the hosted workbench SPA, the preview origin, and the entangle blind relay — all on a single port.

npm i -g @thenewlabs/locus-server
locus-server --port 8080

The published package is fully standalone. Everything is bundled at build time:

• dist/relay.js — the entangle blind relay (WebSocket agent registration + relay pipes), bundled from entangle source.
• dist/entangle-client.js — the entangle browser client, injected into the served SPA so window.entangle exists before the app boots.
• dist/cli.js — the launcher.
• web/ — the built locus-web SPA (index.html, preview.html, sw.js, assets/, __locus/bootstrap.js, __locus/agent.js).

There are no runtime dependencies on the entangle source tree.

What it serves

On one plain-HTTP port, distinguished by the Host header:

• View origin — the Locus workbench SPA. Capability URLs (/cap/<id>) fall through to the SPA so the client reads the capability from the URL.
• Preview host — a preview. subdomain that serves the preview bootstrap and the Service-Worker tunnel bridge.
• Blind relay — WebSocket upgrades at /agent/register and /relay/<capId>.

Options

| Flag | Default | Description | | --- | --- | --- | | --port <n> | 8080 | Port to listen on | | --host <addr> | 0.0.0.0 | Address to bind | | --domain <domain> | — | Convenience: sets --view-origin https://<domain> and --preview-host preview.<domain> unless those are given explicitly | | --view-origin <url> | — | Explicit view origin (e.g. https://locus.example.com) | | --preview-host <host> | — | Explicit preview host (e.g. preview.locus.example.com) | | --output-mode <text\|json> | text | Log output mode |

Production deployment (behind a TLS proxy)

locus-server listens on plain HTTP and expects TLS termination at a front proxy (e.g. Caddy). The proxy must forward the x-forwarded-proto header so the relay can derive the correct frame-ancestors / view origins for the preview iframe.

locus-server --domain locus.thenewlabs.com --port 8080

DNS: point both hostnames at the machine —

locus.thenewlabs.com          A/AAAA -> <host>
preview.locus.thenewlabs.com  A/AAAA -> <host>

Example Caddyfile (Caddy auto-provisions TLS for both names):

locus.thenewlabs.com, preview.locus.thenewlabs.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy sets x-forwarded-proto automatically. If you use a different proxy, ensure that header is forwarded.

Connecting an agent

Once the server is up, point the Locus CLI at it:

locus <dir> --relay https://locus.thenewlabs.com

(That relay is the default once your deployment is configured, so locus <dir> alone works too.)

Build (from the monorepo)

The bundling reads the entangle source and the built locus-web SPA:

npm run build --workspace=@thenewlabs/locus-web     # build the SPA first
npm run build --workspace=@thenewlabs/locus-server  # bundle everything

License

MIT