Skip to main content
Source: packages/oracle-runtime/src/plugins/vfs/
AttributeValue
Visibilityalways
Stabilitystable
Categorydata
Default stateOn (always-on; contributes tools only when the oracle has a UCAN signing key and the user has granted access)
Depends on— (sandbox is an optional sibling — see bridge tools)

​
Summary

The user’s Virtual Filesystem (VFS) — their persistent, access-controlled home for real documents, notes, datasets, and artifacts, in folders, searchable and versioned. This is reusable context that lives across sessions — not sandbox scratch files, not chat attachments, not the web. The oracle acts as the user, inside the exact folder the user delegated to it. The user owns their filesystem and is the sole grantor: only their key can sign the delegation — the oracle can never grant itself access. Every file the oracle reads or writes is confined to the granted subtree and audited as invoker=oracle, actor=user. The filesystem is securely stored with managed encryption; authorized IXO services can read content to power search and previews, so it is not end-to-end encrypted — never describe it as zero-knowledge.

​
How the oracle gets access

The user grants access from the IXO Portal — the oracle never self-grants:
1

User opens their domain's file access

In the Portal: your domain → Library → Files → Access (top-right).
2

User adds the oracle's agent DID

In Manage access, paste the oracle’s account DID (its ORACLE_DID) as the Recipient DID, choose the rights (Read / Write / Delete), set the folder scope and duration, and Grant access.
3

The oracle picks it up automatically

The grant is a UCAN delegation deposited in the UCAN Store Worker, addressed to the oracle. Per request the oracle pulls that delegation and mints a fresh, single-use VFS invocation — no extra wiring. Until a grant exists, the file tools return a short message telling the user how to grant access (including the oracle’s DID).
See Identity and auth for the two-hop UCAN flow (oracle → UCAN Store → VFS).

​
Environment variables

The worker URLs are bundled per network — there is nothing to configure. Everything else is optional tuning.
VarRequiredDescription
NETWORKyesmainnet / testnet / devnet. Selects the bundled VFS + UCAN Store worker URLs (https://[testnet.|devnet.]vfs.ixo.earth). Owned by the core base env schema.
VFS_MAX_READ_LINESnoMax lines a single vfs_read window returns. Default 2000.
VFS_REQUEST_TIMEOUT_MSnoPer-request timeout to the VFS worker. Default 20000.
SANDBOX_MCP_URLnoRead but not owned (declared by sandbox). When set, adds the two sandbox bridge tools.
The oracle’s UCAN signing key (loaded from its Matrix account room at boot) is required — without it the plugin contributes no tools.

​
What it contributes

  • Tools: ten file tools, each resolving a fresh single-use UCAN bearer per call:
    ToolAbilityWhat it does
    vfs_searchfs/readFind files by meaning (hybrid lexical + semantic); returns paths + cited line ranges.
    vfs_grepfs/readFind files containing an exact term.
    vfs_globfs/listMatch files by path pattern, e.g. /notes/*.md, **/*.pdf.
    vfs_listfs/listList a folder’s contents.
    vfs_readfs/readRead a file. Text → windowed numbered lines (page with offset); images/PDFs → transcribed via the vision model.
    vfs_writefs/writeCreate a file (or overwrite when the user asked to replace it).
    vfs_editfs/writeExact-string edit — change one occurrence (or replaceAll).
    vfs_movefs/writeMove or rename a file.
    vfs_deletefs/deleteMove a file to trash (recoverable).
    vfs_sharefs/writePublish a file/folder and return an anyone-with-the-link URL.
  • Sub-agents: none.
  • Middleware: none.
  • HTTP routes: none.
  • Shared state: none.

​
Sandbox bridge tools

When sandbox is configured (SANDBOX_MCP_URL set), two extra tools move a file between the user’s sandbox and their filesystem server-side — the bytes never pass through the LLM:
  • sandbox_to_vfs — persist something the sandbox produced (a report, export, chart) into the user’s files so it survives the session.
  • vfs_to_sandbox — feed one of the user’s files into the sandbox (under /workspace/data/) so sandbox_run code can process it.

​
Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { vfs: false }, // never load
  // features: { vfs: true },  // force on (the default — always bundled)
});

​
When to use it

  • The user refers to a document, note, file, or folder they “saved”, “uploaded”, or “shared with you”.
  • You need to create, update, or organise a file that should persist across sessions.
  • You need to find or quote something from the user’s files (“what did my notes say about X”).
  • You can reuse a file the user already has instead of asking them to re-paste it.
  • The user asks you to share a file or make it downloadable.
  • Persist a sandbox artifact into the user’s files (sandbox_to_vfs), or feed a file into the sandbox (vfs_to_sandbox).

​
When NOT to use it

  • General knowledge or web questions — the files are the user’s private content, not a knowledge base of the world.
  • Content the user pasted directly into chat — act on it inline; don’t write it to a file unless asked.
  • Temporary/scratch files from a compute run — those belong to the sandbox, not the user’s filesystem.
  • Data another plugin owns (flows, skills, memory) — use that plugin.
If a file action reports no access (or read-only), the oracle relays the grant steps above — with its agent DID — so the user can authorize it, then retries. It never claims a file is missing when the real issue is access.

Identity and auth

The two-hop UCAN flow that lets the oracle act as the user.

sandbox

The compute box the VFS bridges to.