@machine-core

Connectors

The webtop connector kind: how a virtual desktop's container filesystem joins the platform's URI filesystem.

machine-core contributes one source connector, kind webtop, over the standard connector port. It backs every machine source, so the container filesystem joins brain-core's URI filesystem like any other source.

Declaration

The manifest declares the connector with the URL scheme machine, default scope user, and a scope selectable across user, project and agent. Every source created on it persists under its own slug, and the slug is the URI scheme: the user-scoped source machine-ops lists its root as machine-ops://, and machine-ops:///config/notes.md addresses /config/notes.md inside that container. All scoped slugs share one connector implementation; the slug is the identity.

The connector advertises fifteen capabilities of the port — list, read, rawRead, write, delete, move, exec, execDetached, scanDelta, walk, count, peekCount, scanContent, subscribeEvents and resolveOsUri. peekCount never makes the trip to the container: it always answers "no cheap estimate", so callers fall back to a real count. Its config schema is closed and empty: a machine source needs no connection settings, because the binding to the live container is resolved at runtime from the active session.

No host path inside the sandbox

resolveOsUri on a machine source returns the container-internal path: machine-ops:///config/x.md resolves to /config/x.md. This is deliberate. The sandbox has no host-side path to expose, so the connector neither fabricates a host path nor reports the location as unresolvable. Host/container path translation only applies to connector kinds that straddle both environments (a host folder on this server); a machine source never participates in it.

Project-scoped, fail-closed

The connector is constructed once per project and captures that project at construction, so two projects that share a slug name can never cross-resolve each other's container filesystems. When no live session is registered for the slug, filesystem calls fail with a typed "no running machine session" error (or return empty for list-class calls), so fs_* tools surface the missing prerequisite instead of succeeding against a placeholder. Filesystem reads acquire no startup authority. Connector execution (Webtop shell) is separate: it requires the real session and may start the machine after the scope, feature and lifecycle checks.

The Webtop filesystem read returns original bytes within the configured read cap, plus a UTF-8 preview or a binary marker; oversized binary reads never expose a partial file as a complete attachment.

On this page