The node service
The node service is the single external front door of a cell. Every
console, SDK, Edge Agent, and external client
authenticates and authorizes here, through one deny-by-default surface,
before anything reaches a backend service. No backend service is exposed
externally in its own right; they are reachable only through this gate.
Feeds: all five product areas. This is the front door in front of every one of them.
What it owns
- Public REST and GraphQL: the primary external API surfaces.
- The agent-tool (MCP) server: how an agent invokes platform tools.
- SFTP: a file-transfer gateway.
- Protocol gateways: external PostgreSQL-wire and Arrow Flight SQL access, proxied to the data engine.
- Reverse proxy and WAF: the proxy and web-application-firewall layer in front of everything.
- Edge listeners: enrollment and operational transports for edge devices.
- Static app hosting: serving the web console and public assets.
Sub-modules (public names)
| Sub-module | What it does |
|---|---|
| Public API (REST / GraphQL) | The external REST and GraphQL surface |
| Agent-tool (MCP) server | Serves tools to agents over MCP |
| Portal | The outside-facing session + permission surface for the Portal Member audience |
| Gateway | Request authorization and routing to backends |
| Reverse proxy & WAF | Proxy and web-application firewall |
| Protocol gateways | External PostgreSQL-wire and Flight SQL access |
| SFTP | File-transfer gateway |
| Edge Agent listeners | Enrollment and operational transports for edge devices |
| Static hosting | Serves the console SPA and public assets |
| Egress | Governed outbound access |
| Deployment | Node-level deployment surface |
APIs and surfaces
The node service is the one place external traffic terminates. Its surfaces
fall into three groups.
Public HTTP. The public REST/GraphQL app, the MCP tool server, static hosting, and the edge REST / WebSocket / DoH / bundle / discovery routes all ride the public HTTP listeners (a clear port and a TLS port). A separate internal control-plane HTTP pair binds loopback (clear) and mutual TLS.
Protocol gateways. External database clients reach the data engine through node gateways: a PostgreSQL-wire gateway on a single port with in-band SSL negotiation, and an Arrow Flight SQL gateway with separate clear and TLS ports. Both proxy to the data service's loopback engine ports.
Edge listeners. A dedicated enrollment listener terminates TLS with no client certificate (devices do not yet hold one at enrollment) and serves exactly one route; a dedicated operational listener requires mutual TLS and carries every route for enrolled devices.
The exact ports, protocols, and auth for all of these are in the Ports & protocols reference.
Three edge/transport surfaces are present in configuration but are not usable as shipped, and each is called out in the ports reference:
- SFTP ships disabled by default. When enabled it binds, but the shipped authenticator denies every credential, so it accepts a connection, refuses the handshake, and closes, exposure with no capability until a real authenticator is supplied.
- The edge MQTT surface is an outbound bridge, not an inbound broker: it binds no port and dials an external broker; the configured MQTT port is read by nothing.
- The SSH tunnel ships disabled by default and cannot serve a device as shipped (the only certificate issuer emits principals the validator rejects) and it refuses to bind without a configured signing CA.
Do not represent any of the three as a live external capability without wiring it.
Workers
The node service runs a metrics publisher and the request-serving runtime
itself; it holds no primary state, so its background work is limited to serving
and telemetry.
Why one door
A platform this broad could easily have grown a door per capability: an object endpoint here, a database port there, a tool server somewhere else, each with its own authentication and its own idea of what a caller may see. That shape is how governance gets lost, because the weakest door sets the actual policy.
Two structural facts follow from refusing it.
The node service is the only front door. Backend services bind loopback for intra-cell callers and a mutual-TLS port advertised on the fabric for peer cells. Neither is an external surface. An external client reaches them through the gateway or not at all.
The admin service owns nothing. The out-of-band diagnostic and control plane attaches read-only and aggregates. The tool you use when things are broken cannot itself be the thing that breaks state.
The middleware stack, in order
Every request passes the same ordered stack before it reaches a route. The order matters: cheap rejections happen before expensive work, and identity is bound before anything scoped is resolved.
Figure: the front-door middleware stack. Amber stages can refuse a request outright. Only a request that clears all of them reaches a route with an identity and a workspace scope bound to it.
Table equivalent
| # | Stage | What it does |
|---|---|---|
| 1 | Request ID | Assigns the correlation identifier the whole path is traced under |
| 2 | Host filter | Refuses a request for a host this node does not serve |
| 3 | IP access | Allow and deny lists, plus geographic filtering |
| 4 | Web application firewall | Inspects the request against the firewall rule set |
| 5 | Rate limit | Per client and per endpoint |
| 6 | Circuit breaker | Sheds load rather than queueing into collapse |
| 7 | Timeout | Bounds the request |
| 8 | Admission | The setup gate lives here: authenticated routes are held until a cell is provisioned |
| 9 | Content type | Validates the declared type |
| 10 | Compression | Applied above a minimum size |
| 11 | Security headers | Added to the response |
| 12 | Metrics | Records the request |
Beyond the ordered stack, identity-bearing middleware binds the service principal (mutual TLS where required), the session, the directory identity, and finally the workspace scope, so a route never has to work out for itself who is calling or which boundary they are in.
A threat-level enforcer sits across this: when the platform's own detection pipeline raises the posture, the gate tightens automatically rather than waiting for an operator.
What the gateway terminates
One door, many protocols. Each is a first-class surface rather than a shim.
Consoles and APIs
| Surface | Notes |
|---|---|
| Public REST API | The primary external surface |
| GraphQL | A merged domain schema with queries, mutations and subscriptions, an auth extension, request context, and query cost analysis so an expensive query is priced before it runs |
| Administrative backend-for-frontend | The console's own API |
| Portal API | The outside-facing session and permission surface |
| Static hosting | The console application and the node's public face, which a customer can replace with their own single-page application |
Data and query access
| Surface | Notes |
|---|---|
| PostgreSQL wire | A gateway on a single port with in-band SSL negotiation, proxied to the engine. A credential resolves to a real directory entity with real grants |
| Arrow Flight SQL | Separate clear and TLS ports, multi-cell fan-out, governed and masked on the wire |
| Iceberg REST catalog | Self-authenticating: the bearer or basic credential is verified in-handler |
| Delta Sharing | The open cross-organization sharing protocol |
| S3, WebHDFS, object REST and gRPC | Object access behind one shared namespace guard |
| SFTP | File transfer through the gateway |
Agents and interop
| Surface | Notes |
|---|---|
| Model Context Protocol server | The agent-tool surface over RPC and server-sent events, with OAuth and token authentication, schema validation, and a path-segment validator that rejects traversal |
| Agent-to-agent | Signed agent cards at the specification's well-known discovery path, a JWKS endpoint publishing the keys, a task endpoint implementing the task lifecycle, and signed push-notification webhooks |
| SPIFFE bundle and workload API | Workload identity documents |
Edge listeners
The device surface is deliberately split in two, because the two halves have different trust properties.
- An enrollment listener terminates TLS with no client certificate, because a device does not hold one yet at enrollment, and serves exactly one route.
- An operational listener requires mutual TLS and carries every route for an already-enrolled device.
Around them sit the WebSocket handler, the MQTT dispatch path, the SSH listener, DNS-over-HTTPS routes, and offline bundle ingest for the air-gapped courier route.
SFTP ships disabled, and when enabled the shipped authenticator denies every credential, so it accepts the connection, refuses the handshake and closes. The edge MQTT surface is an outbound bridge rather than an inbound broker: it binds no port. The SSH tunnel ships disabled and refuses to bind without a configured signing authority. None of the three should be represented as a live external capability without wiring it first. The ports and protocols reference carries the detail.
Governed egress, the other direction
The gateway governs traffic out as well as in, and the model is unusual enough to state.
One cell per organization and traffic class is elected to own the outbound connection, holding a lease, so cells cannot duplicate a send or split-brain one. A cell that does not own the route forwards through the one that does. Egress ownership has a lifecycle with an intake router, a drain worker for clean handover, and a status surface, so "how is my estate reaching the outside world right now" has an answer.
A compute workload's outbound HTTP is brokered and bound to an attenuated grant, so a job cannot reach a destination outside its own scope.
How this relates to a workspace
The gateway is the door. A workspace is the room.
A request arrives, clears the stack, resolves to a directory entity, and binds a workspace scope. From that point every downstream decision (which catalog assets resolve, which rows and columns come back, which storage namespace is addressable, which inbox is reachable, what it costs and who is recorded as having looked) is made against that scope.
That is why the protocol a caller chose stops mattering once they are through the door, and why a BI tool on the PostgreSQL wire and an agent running inside the cell are governed identically.
In the deployment matrix
node runs identically everywhere. Single-cell, it is the one address a client
uses and the edge listeners are available for on-device agents. Multi-cell, each
cell has its own node surface while node identity (not cell identity) is
what peers recognize. Sovereign / air-gapped, the front door and its edge
listeners work entirely locally; the Edge Agent enrolls and operates against them
with no external dependency.
Related topics
- Platform services overview, why the node is the only front door.
- Core and edge · Edge and fleet, the edge listeners' clients.
- Tools & MCP, the agent-tool surface.
- Ports & protocols reference.