Nextcloud

The Nextcloud VFS mounts a WebDAV server (Nextcloud, ownCloud, Hetzner Storage Share, or any generic WebDAV endpoint) at a prefix such as /nc/. Reads are streaming, with HTTP Range requests for partial reads. For credential and server setup, see Nextcloud Setup. For Python, see the Nextcloud (Python) reference.

Install

Nextcloud requires the optional opendal peer dependency:

pnpm add opendal

Config

import { MountMode, NextcloudVFS, normalizeNextcloudConfig, Workspace } from '@struktoai/mirage-node'

const config = normalizeNextcloudConfig({
  url: process.env.NEXTCLOUD_URL!,
  username: process.env.NEXTCLOUD_USERNAME,
  password: process.env.NEXTCLOUD_PASSWORD,
  // Optional:
  // timeout: 30,
})
const vfs = new NextcloudVFS(config)
const ws = new Workspace({ '/nc/': vfs }, { mode: MountMode.WRITE })

NextcloudVFS accepts a configuration object with the WebDAV URL and optional Basic Auth credentials. Both READ and WRITE mount modes are supported. Use an app password (Settings → Security in Nextcloud) rather than your account password.

Field	Description
`url` required	WebDAV URL of the user’s files, such as `https://cloud.example.com/remote.php/dav/files/alice/`.
`username`	Basic Auth user name; unset sends requests without credentials.
`password` secret	Basic Auth password; use an app password (Settings → Security) rather than the account password.
`verifySsl`	Accepted but not applied: every request verifies the server’s TLS certificate.
`timeout` default `30`	Seconds one WebDAV request mirage sends itself (copy, checksum, quota, properties, search) may take; reads, writes and listings go through OpenDAL and its own timeouts.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Nextcloud mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`nextcloud`, write

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Almost all Unix commands.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man to list every command, and man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `nextcloud`, write |

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man` to list every command, and `man <cmd>` or `<cmd> --help` for one command's usage.

WebDAV resources map directly to virtual paths under the mount prefix. For example, virtual /nc/Documents/notes.md issues HTTP WebDAV requests against <NEXTCLOUD_URL>/Documents/notes.md.

Cache

The Nextcloud VFS caches directory listings in Mirage’s index cache. A listing usually needs one PROPFIND Depth: 1; each file missing a size needs an extra stat request. Cached child entries include sizes, types, and modification times, but not ETags. Subsequent stat operations can reuse those entries.

Example

import { MountMode, NextcloudVFS, normalizeNextcloudConfig, Workspace } from '@struktoai/mirage-node'

const config = normalizeNextcloudConfig({
  url: process.env.NEXTCLOUD_URL!,
  username: process.env.NEXTCLOUD_USERNAME,
  password: process.env.NEXTCLOUD_PASSWORD,
})
const vfs = new NextcloudVFS(config)
const ws = new Workspace({ '/nc/': vfs }, { mode: MountMode.WRITE })

// List files
const ls = await ws.shell('ls -la /nc/')
console.log(await ls.stdoutStr())

// Read a remote document
const doc = await ws.shell('cat /nc/Documents/notes.md')
console.log(await doc.stdoutStr())

// Search document contents
const search = await ws.shell('grep -i "meeting" /nc/Documents/*.md')
console.log(await search.stdoutStr())

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Install

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example

​Install

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Cache

​Example

Install

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Cache

Example