Routes
machine-core's three HTTP routes, their feature gates, and the stream surfaces that live outside the package routes.
machine-core's src/routes/ handlers are discovered by the package loader and
dispatched through the platform's generic package-route catch-all
(/api/packages/@neuralis/machine-core/…). Each declares machine.read, gated
against the caller's real role and grants before the handler runs —
deny-by-default. The standard route contract applies.
| Method | Path | Feature | Purpose |
|---|---|---|---|
| GET | sessions | machine.read | Current session info for a source (?uri=<slug>://); probes container liveness on every call |
| GET | sessions/overview | machine.read | Every machine you can see, its state, and which lifecycle actions you may take |
| POST | sessions | machine.read | Start the kept container for the machine URI in body.uri (or ?uri=), or create one on first use; omitted, the caller's first accessible webtop source is used |
| POST | sessions/stream-pass | machine.read | A single-use pass (browser session only, your own running machine, valid 60 seconds) the widget exchanges for a stream cookie |
| DELETE | sessions | machine.read | Stop the machine — the container and everything in it are kept; a purge flag here is refused with 400 |
| DELETE | sessions/container | machine.read | Delete the container (the profile volume stays); ?purge=1 also destroys the profile of a stopped machine (409 while it runs) |
| GET/POST/PUT/PATCH/DELETE | session/:key/stream/* | machine.read (+machine.control for stream control) | Direct-API proxy of the desktop stream, with server-side credential injection |
| GET | health | machine.read | Docker availability, the caller's project active-session count and the per-source isRunning map |
Owner and project isolation are enforced inside the handlers, not just by the
feature gate: sessions resolves through an owner-scoped probe, so a member can only
see, stop, delete or purge their own machine (a non-owner DELETE returns 404,
not 403, so the machine's existence is never confirmed, and the overview reports
someone else's machine as none); health builds its map only from the caller's
project. A caller-supplied uri is validated against the caller's scope-filtered
accessible sources, so a member cannot spin up an arbitrary-named container. Without
a Docker socket the session routes answer 503 with a docker-unavailable phase.
Surfaces outside the package routes
Two stream surfaces sit on the platform's companion HTTP server (the address
MCP_BASE_URL names, default port 3101): the stream's HTTP proxy at
/machine/<sessionKey>/stream/…, and the WebSocket bridge that takes over the
relative upgrade at that same path. The widget's frame points there because the
stream client loads its assets and opens its socket with same-origin relative URLs
that cannot carry a query string; the stream-pass route opens it.
All three stream surfaces run the same project → machine.read → owner → ready →
path authorization, in that order and deny-by-default. Owner is checked before
readiness on purpose, so a non-owner never learns whether the session exists. The
last step is an allow-list over the stream's endpoints: viewing (the dashboard,
status, screenshots, downloads from the desktop folder) needs machine.read; control
(upload, recording, print, session management, signaling) needs machine.control;
any other route under the stream's API answers 403 — or closes the socket 4403.
The one data socket carries both pictures and input, so without machine.control it
is opened in the stream server's own view-only role, and the client can never choose
that role itself. The companion mounts are implemented inside machine-core so that
gate travels with them.
The tool and shell entry points are on Tools; the connector on Connectors. Packages call machine-core through its typed package API, never through these routes.
Audit trail
Every machine_use call is logged with its action, target, session key, and caller
identity; every Webtop shell call is logged with the command line.