Hosting Gateway

Appearance

Overview ​

The gateway is a Matrix package, not a Linux service. Understanding it means holding two perspectives at once: it is an HTTP server bound to a TCP port, and it is a Matrix actor sending request/reply over NATS. Both views matter.

The pages here introduce the gateway from each angle in order:

PageOne-line scope
What the gateway doesFive-bullet summary of every function.
URL to Matrix routingThe path from /apps/chat/index.js to a Matrix actor and back.
Static assetsHow package dist/browser/ files are served.
App bootstrapThe /api/bootstrap endpoint and what it gives the browser.
NATS WebSocketThe /nats-ws upgrade path and same-origin proxy mode.
Gateway actor surfaceOp signatures of system.gateway.http.

Quick model ​

                     ┌───────────────────────┐
                     │      Browser          │
                     └──────────┬────────────┘
                                │ HTTPS
                                ▼
                       ┌───────────────┐         (production only)
                       │ Caddy (TLS)   │ ◄────── separate process; not part of the gateway
                       └───────┬───────┘
                               │ HTTP, port 3100
                               ▼
                  ┌─────────────────────────┐
                  │  HTTP listener          │  http-listener.ts
                  │  (Matrix Host runtime)  │
                  └─────────────┬───────────┘
                                │
            ┌───────────────────┴────────────────────┐
            │                                        │
            ▼                                        ▼
   ┌─────────────────────┐                ┌─────────────────────┐
   │ Platform handlers   │                │ system.gateway.http │
   │ /healthz, /api/*    │                │ (actor)             │
   │ /nats-ws upgrade    │                │ gateway.http.resolve│
   └─────────────────────┘                │ gateway.http.request│
                                          └──────────┬──────────┘
                                                     │ NATS RR
                                                     ▼
                                          ┌─────────────────────┐
                                          │ <appName>.http      │
                                          │ (asset endpoint     │
                                          │  in the package's   │
                                          │  own runtime)       │
                                          └─────────────────────┘

The gateway's HTTP listener is the Linux-process-level "server." Inside, every non-trivial URL is converted into a Matrix request/reply call that may or may not exit the current process.

Three roles, one package ​

The gateway runtime plays three roles simultaneously:

  1. HTTP server. Listens on host.http.port, accepts WebSocket upgrades, serves health and bootstrap.
  2. Matrix client. Connects to local NATS, calls system.gateway.http, system.runtimes, etc., as ordinary Matrix request/reply.
  3. Matrix actor host. Mounts SystemGatewayActor and SystemGatewayHttpActor at system.gateway and system.gateway.http. Other Matrix code (Director, system.catalog) calls those actor mounts.

Reading the source: host-http-runtime.ts is the runtime entry; it both starts the HTTP listener (MatrixHostHttpGatewayServer from http-listener.ts) and mounts the actor (from index.ts).

Caddy is NOT the gateway ​

A common confusion: Caddy is the production TLS terminator. It listens on 443 and proxies to the gateway on 3100. The gateway is what actually runs the route resolution. Caddy does no Matrix awareness.

This is why local development doesn't need Caddy — start the Host (hivecast start), browse to http://127.0.0.1:3100/apps/chat/, and the gateway directly serves the response.

See also ​