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

> Virtualize Nextcloud or any WebDAV server from Node.

`NextcloudVFS` mounts a [WebDAV](http://www.webdav.org/specs/rfc4918.html)
server: Nextcloud, ownCloud, Hetzner Storage Share or any other WebDAV
endpoint. Its folders and files appear as they are, with their own names and
bytes. Set up the URL and app password as in [Nextcloud setup](https://docs.mirage.strukto.ai/home/setup/nextcloud.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node opendal
```

`opendal` is an optional peer package that only this mount needs.

## Configure

```ts theme={null}
import { MountMode, NextcloudVFS, Workspace } from '@struktoai/mirage-node'

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

const result = await ws.shell("ls /nc && find /nc -name '*.md'")
console.log(result.stdoutText)
await ws.close()
```

`url` is the WebDAV URL of the user's files, such as
`https://cloud.example.com/remote.php/dav/files/alice/`. `verifySsl` is
accepted but not applied: every request verifies the server's certificate.

### Fields

**url** `string` *required*

WebDAV URL of the user's files, such as `https://cloud.example.com/remote.php/dav/files/alice/`.

**username** `string`

Basic Auth user name; unset sends requests without credentials.

**password** `string`

Basic Auth password; use an app password (Settings → Security) rather than the account password.

**verifySsl** `boolean`

Accepted but not applied: every request verifies the server's TLS certificate.

**timeout** `number` (default: 30)

Seconds one WebDAV request mirage sends itself (copy, checksum, quota, properties, search, the chunks of a large write) may take; reads, other writes and listings go through OpenDAL and its own timeouts.

Fields marked secret are redacted in snapshots.

## Authentication

The mount sends `username` and `password` as Basic Auth; without them it sends
no credentials. Use an app password (Settings, Security in Nextcloud) rather
than the account password: it can be revoked on its own. A request the server
refuses answers `Permission denied`.

## Layout

```text theme={null}
/nc/
  Documents/
    notes.md
    contract.pdf
  Photos/
    2024/
      cat.jpg
```

`/nc/Documents/notes.md` is `<NEXTCLOUD_URL>/Documents/notes.md` on the
server.

## Behavior

* **Partial reads:** reads stream in chunks, and partial reads such as
  `head -c` send HTTP `Range` requests.
* **Writes:** a write buffers the whole file before it uploads. `cp`, `mv`,
  `rm` and `mkdir` run as WebDAV `COPY`, `MOVE`, `DELETE` and `MKCOL`.
* **Snapshots:** a snapshot keeps the mount's settings but not the password,
  so hand the password back when loading it. Files are not checked for
  changes on replay.

## Integration

Nextcloud answers these commands through its own API, so fewer files are read.
See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `md5sum`, `sha256sum` and the other hash commands: the digest Nextcloud
  keeps (`oc:checksums`), when the uploading client set one.
* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Nextcloud mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **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 <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## 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 <cmd>` or `<cmd> --help` for one command's usage.
> ```


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