# Connectors (https://docs.neuralisapp.com/machine-core/connectors)

machine-core contributes one source connector, kind `webtop`, over the standard
[connector port](https://docs.neuralisapp.com/package-system/connectors.md). It backs every machine source, so
the container filesystem joins brain-core's
[URI filesystem](https://docs.neuralisapp.com/brain-core/connectors.md) like any other source.

## Declaration [#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 [#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 [#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.
