Workspaces & files
Workspaces, nodes & files
The content model your extensions read and write — workspaces, the virtual file system, nodes, paths and versions.
Your extensions operate on a workspace's content. Here's the model from an integrator's point of view.
Workspaces
A workspace is an isolated tenant container: its own files, members, roles and installed extensions. Everything your extension does happens within a workspace — tokens are scoped to one, and an extension installed in workspace A is not available in workspace B unless installed there too.
In a deployed environment, each workspace is reachable at {workspace}.<domain> (the workspace app),
while all API calls go through the shared api.<domain> gateway.
The virtual file system (VFS)
A workspace exposes a hierarchical virtual file system. Files and folders live at paths (e.g.
/reports/q1.csv). The VFS is also where extensions are installed — their manifests are just files in
the VFS.
VFS paths are SDK/API identifiers, not browser routes. In the workspace UI, / is the home dashboard,
the VFS root is /files, and a file such as /reports/q1.csv is opened at
/files/reports/q1.csv. See Workspace shell & routes for canonical URLs
and the no-redirect migration from the former root catch-all.
Manifests are files too
There's nothing special about a manifest from the file system's perspective — smart-editor.app.yaml
is a file at a path. Placing it installs the app; removing it uninstalls it.
Nodes, content and versions
Under the hood the VFS is backed by nodes:
NodeThe addressable item at a path — a file or folder. A node has a stable identity independent of its current path.
ContentThe stored bytes of a file node, with a MIME type. This is what apps render and engines read/write.
VersionFiles are versioned. Writing new content creates a new version; the node's "head" points at the latest.
Path / path entryThe human-readable location of a node in the tree. A node can be addressed by id or by path.
How extensions touch content
- Apps read (and optionally write) the file the user opened, through the SDK bridge — without ever handling raw credentials.
- Engines read their input file(s) and can write outputs back into the VFS, using a scoped token minted for the run.
The permissions that allow these operations are declared in your manifest and enforced by the token system — see Identities & tokens and Working with files & nodes.