machine-core

@neuralis/machine-core is the workforce's hands and eyes: every user gets a persistent virtual desktop — a full Linux desktop (XFCE on Ubuntu, based on LinuxServer Webtop) running in its own Docker container and streamed into the workspace as a widget over Selkies. An agent does not get a browser-shaped API; it gets a computer. Agents drive that desktop at three layers, all against the same live session:

The desktop is stateful across turns: browser logins stick, installed applications stick, and files under /config/ stay on disk. The container filesystem is also mounted as a regular source (machine://), so agents read and write sandbox files with the standard fs_* tools — see machine sources.

What the package providesCopy Anchor Link

• Session management. Webtop containers are spawned lazily per (project, source) through the host Docker socket, and then KEPT: an idle machine is stopped, never thrown away, so the next start takes seconds and everything installed inside it is still there. Deleting the container is an explicit act, and the persistent profile volume survives even that — the desktop feels like your machine.
• Authenticated streaming. The Selkies HTTP and WebSocket stream is reverse-proxied through package routes with server-side Basic-auth injection — the browser never sees the stream credential. Minimizing the widget stops the pixels and leaves the machine running: the desktop, the browser session and anything an agent is doing on it carry on untouched, and reopening the widget picks the stream back up.
• Drive and shell. machine_use retains its action enum and chromium | desktop target; agent-core’s execute routes shell work by source URI. See the machine_use tool.
• Vision capture. Screenshots come back as native image content blocks that vision-capable models consume directly. Screen recordings are written to the machine's recordings directory and returned as a data://machine-core/recordings/<file> URI; the model loads it with fs_read when it needs the footage, and the platform then delivers it in the best form the active model can ingest.
• A machine filesystem source. The manifest declares the webtop connector kind and one machine source instance on it, so the container filesystem is addressable at machine-…:// and reachable with the standard fs_* tools — see machine sources.
• Skills and an always-active safety rule. manage-machine-sessions wraps the session lifecycle routes, machine-driving teaches the observe-act cadence, and rules/machine-safety.md supplies automatic constraints for machine operations when the package’s contributions are enabled — see machine-core skills.
• A workspace widget. The Machine widget and its dock entry are declared in the manifest as App surfaces; the widget requires the machine.read feature to appear at all.

Feature tiersCopy Anchor Link

The manifest declares three features and grants them by role, deny-by-default — the standard features and access model:

machine_use carries machine.read as its declared baseline gate; drive-class actions escalate to machine.drive inside the handler because the required feature depends on the action argument. Webtop shell through execute is the platform's exec rule: core.execute for the tool, the connector-DECLARED entry exec.machine, then the source's own exec policy on the directory the command starts in — after which the provider checks source scope and lifecycle authority. Owners adjust grants per role through the platform role configuration.

The desktop stream follows the same split. With machine.read alone you watch your desktop live, but the stream server drops every keystroke, click, paste and resize from your browser, and the widget header shows a View only badge so a picture that ignores input never reads as broken. With machine.drive you control it — and stream control is as powerful as the machine's own shell (a keyboard into a terminal, or the dashboard's command runner), so grant it with the same care as exec.machine. A default member gets the view-only stream until an admin grants machine.drive, which also lets that member's agents run drive actions.

RoutesCopy Anchor Link

Safety modelCopy Anchor Link

Every machine_use call is audit-logged with its action, target, session key, and caller identity; every Webtop shell call is logged with the command. Each session is owned by the user who started it: a project member can only inspect, stop, or stream their own session, and the container filesystem (machine-…:// via fs_*) is scoped to the owning project. The shell command denylist is cosmetic friction, not a security boundary — the real boundary is the container sandbox plus the exec.machine feature grant plus network isolation. Dangerous key combos are rejected on the desktop, and recording goes exclusively through the capped record action. The package also ships an always-active safety rule and driving guidance — see machine-core skills.

Default workflow templateCopy Anchor Link

The package ships a Web watch workflow template: a scheduled browser monitor that visits your URLs, extracts the meaningful content, diffs it against the previous snapshot, and reports only real changes — pair it with a channel binding to get alerts in Telegram or WhatsApp. It requires machine access, so only roles that can drive the machine see it.

Folder mapCopy Anchor Link

The pages in this section mirror machine-core's real package folders, so the docs map one-to-one onto the code:

In this sectionCopy Anchor Link