Community container: Assistant agent chat over your own data, without AppAPI/ExApp

[cbcoutinho]

I'd like to add a community container that gives AIO users the Nextcloud Assistant's "Chat with AI" agent — the one that can actually look things up in your own files, notes, calendar, contacts and Deck cards, and answer with links back to what it used.

Today that needs Nextcloud's Context Agent app, which is an ExApp: it only runs through AppAPI plus a deploy daemon (HaRP, or previously the Docker Socket Proxy). In AIO that is a real hurdle, and it means giving Nextcloud reach into a Docker socket. A fair number of threads here are about exactly that friction:

• Cannot install ExApps #6613 Cannot install ExApps
• 🐳 Nextcloud AIO – Fix “HaRP daemon not accessible” error #8469 Fix "HaRP daemon not accessible" error
• HaRP migration lacks documentation - where is the password? #8159 HaRP migration lacks documentation - where is the password?
• Old docker_aio AppAPI daemon remains registered after AIO 12.9.1 Beta migration from Docker Proxy to HaRP #7861 / Old docker_aio AppAPI daemon remains registered after AIO 12.9.1 Beta migration from Docker Proxy to HaRP #7848 Old docker_aio AppAPI daemon remains registered after migration
• AppAPI default deploy daemon "docker_aio" is not accessible. with AIO v12.1.4 on latest Docker #7221 AppAPI default deploy daemon "docker_aio" is not accessible
• app api gets disabled on start up regardless if it has daemons configured when the harp container is diabled #8225 app api gets disabled on start up regardless if it has daemons configured

The Astrolabe app (0.39.0+) removes that requirement. It registers an ordinary in-process TaskProcessing provider for the core task type core:contextagent:interaction, and the Assistant treats its agent as available as soon as any provider claims that type. So: no AppAPI, no ExApp, no Context Chat, no Docker socket. The retrieval itself runs against nextcloud-mcp-server, which is what the container would run.

What it would look like

One service, ghcr.io/cbcoutinho/nextcloud-mcp-server. Nextcloud reaches it over the Docker network, so the Assistant agent needs nothing exposed. Port 8000 is published so that an admin who also wants to connect an external MCP client (Claude Desktop, an IDE) can reverse-proxy mcp.$NC_DOMAIN at it — the same shape the vaultwarden community container uses with bw.$NC_DOMAIN. That step is optional; skipping it costs only the external-client use case.

Everything on the Nextcloud side is done through nextcloud_exec_commands: install and enable oidc, astrolabe and assistant, register two OIDC clients (a public one for the Astrolabe app, and a confidential one for the MCP server itself) using AIO-generated secrets as their credentials, point Astrolabe at the MCP server, and switch the agent on. Nothing for the admin to configure by hand.

Deliberately kept small for a first version:

• No LLM is bundled and none is called by the container. Astrolabe does retrieval only. Every generated word comes from whatever TaskProcessing provider the admin already has serving core:text2text:chatwithtools — typically integration_openai pointed at OpenAI, a compatible endpoint, or a local model (the existing local-ai community container works for that).
• Semantic search and background indexing are off. Nothing is embedded, indexed or copied into a vector database; the agent reads through Nextcloud's own APIs, live, as the user asking the question. Adding semantic search would mean bringing in a vector database and an embedding model, so I'd rather propose that separately once the basic container has proven itself.
• Read-only scopes (files.read notes.read webdav.read calendar.read contacts.read deck.read). The MCP server hides every tool those scopes don't grant, so the agent cannot modify content.
• Each user opts in once from the Astrolabe app before the agent can act for them.

Two things already in AIO make this work cleanly and are worth calling out:

• AIO already runs occ taskprocessing:worker under supervisord, which is normally the number one reason an agent chat appears to hang elsewhere.
• The generated secrets can be handed to occ oidc:create --client_id / --client_secret, so both OIDC clients are created idempotently with no admin copy-paste step, and the MCP server gets a static client rather than a dynamically registered one that the oidc app would delete after an hour.

One thing I'd like input on

The MCP server stores each user's Nextcloud credential encrypted at rest, and its TOKEN_ENCRYPTION_KEY currently has to be a Fernet key — base64url-encoded 32 bytes. AIO generates secrets as bin2hex(random_bytes(24)), i.e. 48 hex characters, which Fernet rejects, and a community container has no settings UI where an admin could paste a real key instead.

So there's a small mismatch to resolve. Options I can see, and I'd welcome a steer on which fits AIO best:

1. Have the MCP server accept any sufficiently random string and derive the encryption key from it, keeping existing Fernet keys working unchanged. Entirely on my side; no AIO change. This is my default unless someone objects.
2. Have the container generate and persist its own key in its data volume on first start, and ignore the AIO secret. Self-contained, but the key then lives only in that volume.
3. Something in AIO for secrets that need a specific encoding — but that seems like a lot of machinery for one container, so I'm not proposing it, only mentioning it for completeness.

Happy to go with (1) unless there's a reason to prefer otherwise.

Ask

Does this sound like a reasonable community container? I've opened #8489 as a draft with the implementation so there's something concrete to look at. If the direction is fine I'll finish the encryption-key piece, test it on a live instance, and mark it ready — and it would be good to have it listed under #5251.

I maintain both the app and the server image, so I'd be the maintainer for this container.

---

This PR was generated with the help of AI, and reviewed by a Human

[szaimen]

Hi, lets continue with this in #8489 :)