Skip to main content

Nextcloud

Istota does not require Nextcloud. When configured, it can use Nextcloud for file storage, sharing, contacts, OAuth login, notifications, Talk, and calendars through CalDAV. Without it, the stack uses local storage, built-in web chat, email sign-in, and an optional external CalDAV server.

The nextcloud skill is the agent's control surface over a connected server: what it supports, who is on it, what is shared with whom, and the file operations the mounted filesystem cannot express.

Everything runs as the bot's own Nextcloud account (nextcloud.username / nextcloud.app_password). That is the accurate identity for the operations in scope: the workspace layout lives in the bot's storage and is shared out to each user, and the bot is the Talk participant. There is no --as-user mode — Istota does hold per-user Nextcloud OAuth tokens, but their encryption key is delivered to the web unit only and deliberately never reaches a task environment.

Availability​

The skill declares requires_capability: [nextcloud], satisfied when nextcloud.url is set. On an install with no Nextcloud it disappears from selection and from the on-demand menu entirely, rather than offering verbs that would all fail.

Reading and writing ordinary files is not part of this skill. The files skill and ordinary POSIX tools handle that, everywhere, with or without Nextcloud.

Where the workspace lives​

With Nextcloud configured, the workspace is either the bot's Nextcloud files through the VM's rclone mount, or a local directory on the VM. istota setup asks which (--workspace mount|local, default mount); workspace_mount_path in config.toml records the answer, set for the mount and absent for local. See Storage.

Talk, the user, group and capability verbs, share listing and avatars work in both. On a local workspace, talk share-file uploads a copy of the file into the bot's Talk/ folder before posting it, so a later edit to the workspace file does not reach the posted one. The files verbs, share create and share link act on the same path in the bot's Nextcloud tree, which is not the workspace there, so they refuse and point to talk share-file and the web UI. dav_prefix and auto_share_bot_dir below only matter with the mount.

Command groups​

istota-skill nextcloud capabilities [--raw] [--check a,b]
istota-skill nextcloud user whoami|search|get|groups
istota-skill nextcloud group list|members
istota-skill nextcloud share link|list|get|create|update|revoke|delete|search
istota-skill nextcloud files stat|list|search|upload|download|versions|restore-version|trash|favorite|quota
istota-skill nextcloud talk rooms|room|create|rename|describe|invite|participants|read|send|share-file|mentions|search|leave|delete
istota-skill nextcloud notify list|get|dismiss|dismiss-all
istota-skill nextcloud activity list

All output is JSON. istota-skill nextcloud <group> --help lists a group's flags.

Errors carry the reason​

Every failure is a structured envelope rather than a bare string:

{
"status": "error",
"error": "Unauthorised — this endpoint usually requires admin rights…",
"http_status": 200,
"ocs_status": 997,
"endpoint": "/cloud/users/alice"
}

ocs_status: 997 on a provisioning endpoint almost always means the bot is a regular user on that server, so the message names admin rights as the likely cause and points at user search as the alternative. The same envelope shape is what scheduler._execute_command_task detects, so a failed verb marks the task failed with the server's message intact.

capabilities — the deployment fit-check​

istota nextcloud capabilities # operator shell
istota nextcloud capabilities --check sharing.public,talk # exits non-zero if missing
istota-skill nextcloud capabilities # from a task

One call reports server version and edition, the WebDAV root, the sharing knobs (public links enabled, password enforced, maximum expiry), Talk features, notification endpoints, activity API, versioning and undelete, chunked upload, and the bot account's quota.

--check takes dotted feature names and exits non-zero when one is missing, so it works as a deployment gate in a shell or a heartbeat shell-command check. Names:

NameMeaning
sharing, sharing.apiSharing app present / API enabled
sharing.publicPublic links allowed
sharing.public.password_enforcedServer requires a password on links
sharing.public.expire_date, sharing.public.expire_date_enforcedLink expiry available / mandatory
sharing.resharing, sharing.federation, sharing.emailResharing, federated shares, email shares
talkTalk (spreed) installed
notifications, activityNotification and activity apps
files.versioning, files.undeleteVersion history, trash bin
dav.chunkingChunked upload

This is the verb to reach for when a managed Nextcloud refuses something and it isn't clear whether it's a permissions problem or a missing app.

share link is the answer to "give me a download link":

istota-skill nextcloud share link "/Users/alice/report.pdf"
istota-skill nextcloud share link "/Users/alice/report.pdf" --days 3 --password-generate
istota-skill nextcloud share link "/Users/alice/project" --file notes.md

A link share is live (it serves the current file, not a copy), revocable, expiring, and optionally passworded. It applies nextcloud.share_default_expire_days (default 14) unless --days 0 opts out, and clamps to the server's enforced maximum with a notice saying it did.

The response carries the whole lifecycle: url, download_url, token, share_id, expires, has_password, permissions, and a literal revoke_command. download_url matters because a link share resolves to a preview page, not a file — a file or whole folder takes /download, and --file NAME targets one entry inside a shared folder.

share revoke closes the loop by id, by token, or across a path. The path form can remove several links at once, so it refuses without --confirmed.

A public link is for giving a file to someone else. It is a bearer URL: anyone who ends up holding it can open the file, so "who did I show this to" stops being answerable. That makes it the wrong instrument for handing a user a file they already own — in web chat the assistant uses the authenticated GET /api/chat/files?path= download instead (see config/guidelines/web.md), and in Talk the file is already in the user's Nextcloud. The confirmation rule follows from that: a user asking for a link is itself the authorization, the assistant deciding a link would be handy for the requesting user means not creating one at all, and any other recipient is confirmed every time. --type user|group is the narrower instrument whenever the recipient is known — revocable, attributable, and reaching exactly one account.

Expiry is computed from UTC, not the local clock, because Nextcloud evaluates it against its own. A caller west of the server rolls over later than the server does, so a local base makes --days 1 land on a date the server already calls past — a several-hour window every day, and a hard failure rather than a wrong date. A server running ahead of UTC can still see a one-day expiry as same-day; that residual would need the date from the server itself.

Nextcloud rate-limits share creation to 20 per 10 minutes per account. Past that, every attempt returns a 429 whose message names the cap and, when the server sends Retry-After, how long to wait — a bare status code gives an agent nothing to decide on, and the skill tells it to report the wait rather than retry into another refusal.

files — only what the filesystem can't do​

There is deliberately no read, write, mkdir, rm, mv or cp. The mount does those with ordinary POSIX calls, and an HTTP variant would give the model two ways to do one thing with no rule for choosing.

What is here:

  • stat / list — server-side properties the filesystem cannot show: fileid (the stable id the versions API keys on), permissions, share_types, favorite, owner_id, preview and mount type.
  • search — indexed, server-side, scoped, filtered by name glob, MIME, minimum size and mtime. A find over the FUSE mount walks the network filesystem and is unusably slow on a large tree.
  • versions / restore-version, trash list|restore|empty, favorite, quota.
  • upload / download — the exception to the rule, for a large file (chunked above a threshold, plain PUT below, and a plain PUT when the server reports no dav.chunking), a file originating outside the mount, and rclone mode, where there is no local path at all.

files trash empty is irreversible and refuses without --confirmed.

talk — a control surface, not a delivery path​

The transport seam and its persistent-loop TalkClient keep owning inbound polling and outbound delivery. This group is for the agent to look a room up, read what was said in one, search history, or deliberately post somewhere other than the current conversation.

talk share-file is the verb that bridges the two surfaces: a Talk attachment is a share of type 10 whose shareWith is the conversation token.

The skill CLI is a one-shot subprocess with no persistent asyncio runtime, so it uses nextcloud.talk.transient_client(config) — the single documented exemption to the "no TalkClient outside the singleton" invariant, recorded in .claude/rules/transport.md.

talk search --token restricts results to one conversation, and does so client-side. The unified-search provider's from parameter looks like the way to scope a search but means "the page I am currently on", so the provider excludes that conversation — passing the requested token there returns every room except the one asked for. The filter matches on each entry's attributes.conversation instead, over-fetching so --limit applies to the matching subset.

notify / activity​

Read and dismiss only. Sending a Nextcloud notification needs the admin_notifications app and admin rights, and the bot already has two working push channels to its own user (ntfy and Talk), so the send path is deferred rather than half-built. dismiss-all is gated on the server advertising the delete-all endpoint.

Both feeds are bounded by default (25 entries) — an unbounded activity stream is a context-flooding hazard.

Sharing calendars and address books with Istota​

Tasks read a user's calendars and address books through the bot's own account, so the user shares each one with the bot. They can do that in the Nextcloud Calendar and Contacts apps, or from the Nextcloud card in Settings > Connections.

The card lists every calendar and address book the user owns, each with No access, Read-only or Read and write. Saving creates, changes or removes the DAV share from that collection to the bot account, sent with the user's own Nextcloud OAuth token from the web process. Calendars and address books other people shared with the user, the birthday calendar, "Recently contacted" and the system address book "Accounts" are not listed. Nextcloud holds the share state and Istota stores none, so a share made or removed in the Nextcloud apps shows on the card the next time it loads. A change counts as done only when re-reading the collection shows it: Nextcloud answers 200 to a share it did not apply, for example with sharing switched off for the instance, and the card then reports "Nextcloud did not apply this change" on that row.

The card needs [web] token_storage = "encrypted", which istota setup writes on the stack. With ephemeral storage, the card shows only the connection state, and sharing is done in the Nextcloud apps. The token itself never reaches a task; tasks still see only what is shared with the bot account.

Disconnecting asks whether to stop sharing as well. "Disconnect and stop sharing" removes the bot's shares first and deletes the token only once nothing is left shared, since removing a share needs the token. "Disconnect, keep sharing" leaves the shares in place. A share to a group the bot belongs to is not shown and is not removed.

The operator caps what users may share with [nextcloud.sharing] (below). The cap limits raising access only: a user can always lower a share or remove it, and a share made by hand above the cap is shown at its real level. Calendars are not offered when tasks read calendars through another account ([caldav] url set, or a [caldav] username other than the bot's).

Trust posture​

Inbound is untrusted. Talk messages, participant and room names, share notes, notifications and activity entries are all text other people wrote. Every such payload comes back wrapped in an explicit untrusted-content delimiter, and the skill declares companion_skills: [untrusted_input, sensitive_actions] so the inbound-handling guidance arrives whether the skill was selected eagerly or pulled from the menu. A room the bot merely sits in is an ingestion surface.

Outbound is confirmation-gated. Creating a share, sending a Talk message, posting a file into a room and inviting a participant all reach other people. Two narrow exemptions, stated in the skill body rather than left to inference: a share with the task's own user, and a message to a room where the user is the only other participant.

Destructive verbs default to refusing. talk delete, files trash empty and share revoke --path return {"needs_confirmation": true, …} without --confirmed, so the model gets a machine-readable "this needs a confirmation turn" rather than an indistinguishable failure.

Paths are scoped to the caller. The bot's credentials reach every user's workspace; the skill must not. files and share verbs resolve a caller-supplied path against /Users/<caller>/ and refuse anything escaping it (after .. normalization) unless the caller is an admin.

The status file​

With Nextcloud configured, the daemon writes status.json at the root of the bot account's files for a Nextcloud app to read: the bot's name and version, when it started, its worker pool and its queue, and updated_at. The daemon checks once a minute and writes the file when the worker or queue counts change, and otherwise every five minutes. A reader that takes an old updated_at to mean the daemon has stopped needs a threshold above five minutes.

Configuration​

[nextcloud]
url = "https://nextcloud.example.com"
username = "istota"
app_password = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
share_default_expire_days = 14 # 0 = no default expiry on `share link`
dav_prefix = "" # mount point of the storage root in the bot's own tree
auto_share_bot_dir = true # share the bot workspace back to the user at boot

[nextcloud.sharing]
calendars = "full" # the most the Nextcloud card may share: "off", "readonly" or "full"
contacts = "full"

dav_prefix exists because the bot's storage root and the root of its Nextcloud file tree are not always the same directory. When the VM's rclone mount is rooted at the top of the bot's files they are, and it stays empty. When the mount is rooted at a folder inside them, /Users/alice on disk is, say, /Shared Files/Users/alice over DAV and OCS; the value is that folder (istota setup asks for it), and the request layer puts it in front of every path on the way out and strips it on the way back. Paths on disk, and the paths the skill takes and returns, are unaffected — they stay logical.

[nextcloud.sharing] is the ceiling for the Nextcloud card in Settings > Connections. An invalid value warns and falls back to "off", and istota apply refuses a plan carrying one.

auto_share_bot_dir controls the OCS share of the bot workspace back to the user that runs on every boot. Leave it true unless the Nextcloud already puts that directory in the user's file tree some other way. The Nextcloud the old stack bundled did, through a files_external mount, and set this false so the user was not handed the same folder twice; one moved out of it keeps that value.

Sharing off a files_external mount needs the mount to allow it. Nextcloud defaults enable_sharing to false there, and every share of anything under the mount is then refused with "You are not allowed to share". The old stack's provision-nc.sh turned it on for both mounts it created; a Nextcloud whose bot storage is external storage set up some other way needs occ files_external:option <mount_id> enable_sharing true.

Credentials reach the skill as NC_URL / NC_USER / NC_PASS, and dav_prefix as NC_DAV_PREFIX. Only NC_PASS is sensitive, so it is stripped from the model's environment and injected server-side by the skill proxy. With the proxy off, the Nextcloud host is added to the CONNECT allowlist when the skill is authorized.

Client internals​

The client lives in src/istota/nextcloud/:

ModuleContents
_http.pyocs_request + ocs_get/post/put/delete, dav_request, OcsError, the OCS status table, path scoping
capabilities.pyCapabilities probe, feature map, --check evaluation
shares.pyShare CRUD, the link helper, download-URL synthesis
users.pywhoami, autocomplete search, groups
dav.pyPROPFIND, SEARCH, versions, trash, upload/download, favorites, quota
notifications.pyNotifications and activity reads

src/istota/nextcloud/compat.py remains as a back-compat shim holding the None-returning variants four best-effort daemon paths depend on: startup user hydration, the ocs_share_folder pre-check, the shared-file organizer's owner lookup, and !search. A Nextcloud hiccup must not fail daemon startup, so those keep the historical contract; only the CLI takes the raising path.