> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nextcloud

> Mount Nextcloud over WebDAV as a filesystem and read or write your files with shell commands.

The Nextcloud VFS mounts a [WebDAV](http://www.webdav.org/specs/rfc4918.html)
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](https://docs.mirage.strukto.ai/home/setup/nextcloud.md).
For Python, see the [Nextcloud (Python)](https://docs.mirage.strukto.ai/python/vfs/nextcloud.md) reference.

## Install

Nextcloud requires the optional `opendal` peer dependency:

```bash theme={null}
pnpm add opendal
```

## Config

```typescript theme={null}
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](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Nextcloud mounted at `/<path>`.

**Rendered**

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

**Raw**

```markdown theme={null}
---
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

```typescript theme={null}
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())
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.