# Routes (https://docs.neuralisapp.com/machine-core/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](https://docs.neuralisapp.com/package-system/routes.md) 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 [#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](https://docs.neuralisapp.com/machine-core/tools.md); the
connector on [Connectors](https://docs.neuralisapp.com/machine-core/connectors.md). Packages call machine-core
through its typed package API, never through these routes.

<Callout type="info" title="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.
</Callout>
