Nextcloud Talk Setup

Full voice + chat support. Connect your Nextcloud instance to let your agent join Talk rooms.

Capabilities: audio_inaudio_outreadwritetypingfiles

Prerequisites

Before connecting, your Nextcloud instance must have the Chamade for Talk addon installed. This addon manages bot user creation and authorization. You need admin access to the Nextcloud instance.

Install from the Nextcloud App Store

The easiest way: Chamade for Talk is published on the official Nextcloud App Store and can be installed in one click from your instance's admin UI.

Prefer the command line? Run this as the web user on your Nextcloud server:

sudo -u www-data php occ app:install chamade_talk

On Nextcloud AIO, prefix with docker exec -u www-data nextcloud-aio-nextcloud. The App Store installer fetches the signed archive directly from Codeberg, verifies the signature, and enables the app — no manual download needed.

Connect your instance

Behind the scenes, the addon creates a dedicated bot user named "Chamade (your_username)" on your Nextcloud instance. The bot is placed in a visibility group with you, so other users on the instance won't see it (on instances with group-based user visibility).

Authorization & privacy

The bot is scoped to your Nextcloud account. Other users on the instance cannot use it without your consent:

• Direct messages: Only you can DM the bot. Messages from other users are silently ignored.
• Group rooms: The bot is inactive by default. Type /activate in a room to enable it. Only you (the account owner) can activate or deactivate the bot.
• Deactivate: Type /deactivate in a room to disable the bot. The bot stays in the room but stops responding.

Join a voice call

Once connected, your agent can join any Talk room on your Nextcloud instance by providing the room URL.

chamade_call_join(platform: "nctalk", meeting_url: "https://cloud.example.com/call/abc123")

curl -X POST https://chamade.io/api/call \
  -H "X-API-Key: chmd_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "nctalk", "meeting_url": "https://cloud.example.com/call/abc123"}'

The meeting_url is the Talk room URL from your Nextcloud instance. You can find it in your browser's address bar when inside a Talk conversation.

Disconnect

To disconnect your Nextcloud instance:

This removes the connection from Chamade and deletes the bot user from your Nextcloud instance. You can reconnect at any time.

Message limits & formatting

Manual install (fallback)

If the App Store is unreachable from your instance (air-gapped deployment, network restrictions, store downtime), you can install Chamade for Talk v2.2.5 by hand from a signed archive we host for you.

# Download the addon
curl -Lo /tmp/chamade_talk.tar.gz https://chamade.io/static/chamade_talk-3.0.0.tar.gz

# Copy into container and extract
docker cp /tmp/chamade_talk.tar.gz nextcloud-aio-nextcloud:/tmp/
docker exec nextcloud-aio-nextcloud bash -c \
  "tar xzf /tmp/chamade_talk.tar.gz -C /var/www/html/custom_apps/ && rm /tmp/chamade_talk.tar.gz"

# Fix permissions and enable
docker exec nextcloud-aio-nextcloud chown -R www-data:www-data /var/www/html/custom_apps/chamade_talk
docker exec -u www-data nextcloud-aio-nextcloud php occ app:enable chamade_talk

# Download and extract into apps directory
curl -Lo /tmp/chamade_talk.tar.gz https://chamade.io/static/chamade_talk-3.0.0.tar.gz
tar xzf /tmp/chamade_talk.tar.gz -C /var/www/nextcloud/apps/

# Fix permissions and enable
chown -R www-data:www-data /var/www/nextcloud/apps/chamade_talk
sudo -u www-data php /var/www/nextcloud/occ app:enable chamade_talk

For future upgrades, always prefer the App Store path — it handles signature checks and upgrade migrations automatically.

File attachments

NC Talk supports send and receive. Outbound: pass attachments: [{file_id} | {url} | {bytes_b64, name, mime}] on chamade_dm_chat or chamade_call_chat — Chamade uploads via WebDAV under the bot user, creates an OCS share (shareType=10), and posts the caption via talkMetaData. Cap 25 MB per file. Send works on any addon version.

Refetching uses a WebDAV GET with the bot user’s credentials on the forwarded path, with a PROPFIND fallback on file_id if the path has moved. See Files API for the full flow.

Privacy mode (E2EE)

Privacy mode encrypts chat messages between you and your agent end-to-end. Chamade sees only opaque ciphertext on the wire and has no way to read the content. It uses sealed-box-x25519 (libsodium) — a fresh ephemeral key per message, no session state to manage.

What is and isn't encrypted

Trust model

Privacy mode protects against Chamade infrastructure compromise — a malicious or breached gateway cannot read your chats. It does not protect against:

• Your Nextcloud server. NC Talk is not natively E2EE, so the server sees plaintext to display messages in the web UI. The threat model assumes you trust your own NC instance — typically because you self-host.
• Your local machine. The shim stores private keys in ~/.chamade/e2ee/. Anyone with read access to that directory can decrypt traffic.
• Your agent. The agent sees plaintext after decryption — that's the point. Pick an agent runtime you trust.

Requirements

• Chamade for Talk addon v3.0.0 or newer on your Nextcloud instance. Older addons don't advertise the e2ee capability and Chamade transparently keeps plaintext routing.
• Local MCP shim (the @chamade/mcp-server npm package running over stdio). The hosted HTTP MCP at mcp.chamade.io cannot do E2EE by design — it would run server-side and see your keys.

Setup

One-time bidirectional key paste. Two surfaces (shim CLI and NC admin), two pubkeys, four fingerprints to eyeball.

chamade_e2ee_enable(platform: "nctalk", account_id: "<your_nc_url>")

chamade_e2ee_register_peer(platform: "nctalk", account_id: "<your_nc_url>", peer_pubkey: "<addon_pubkey>")

From this point on, every chat message between you and your agent transits as opaque ciphertext through Chamade. The agent never notices anything different — the shim decrypts inbound and encrypts outbound transparently in its tool calls.

Dashboard status

The Chamade dashboard surfaces four privacy-mode indicators per NC Talk connection. All four green = end-to-end encryption is wired and observed working:

If a voyant is red, Chamade points at the missing link — without ever holding a pubkey or a plaintext message itself. The indicators come from heartbeat metadata (booleans + timestamps).

Multiple devices

You can register more than one shim against the same NC instance — each shim has its own keypair. When the addon encrypts user→agent traffic, it fans out one ciphertext per device. When any shim encrypts agent→user traffic, it encrypts to the single addon pubkey. Adding or removing devices is a per-shim paste; existing devices are unaffected.

Disabling

Either side can flip back to plaintext at any time — toggle off in the addon admin, or call chamade_e2ee_disable on the shim. Existing in-flight messages decrypt normally; new ones revert to plaintext. There's no history to lose (the agent use case doesn't rely on scrollback).

Voice and Privacy mode

Voice traffic on NC Talk is not encrypted end-to-end and won't be in this iteration. Chamade has to join the WebRTC call as a participant to pipe audio to the agent's STT/TTS — if it couldn't see the PCM, it couldn't route a single sample. True end-to-end voice would require the shim itself to act as a WebRTC client with local STT/TTS, which is a different product. Be explicit with your users that "privacy mode" on Chamade means chat content, not metadata and not audio.