Nextcloud AI Setup Guide: Local and External Backends

Nextcloud AI (part of Nextcloud Hub) is an open-source AI assistant built directly into your file-sharing platform. It lets you run language models, image recognition, transcription, and more without sending your data to external servers. This guide covers what Nextcloud AI can do, how to set it up, and whether local or external AI makes sense for your team.

What Is Nextcloud AI?

Nextcloud AI is a suite of features released as part of Nextcloud Hub 6 (September 2023) and available in all subsequent Hub versions, including Hub 35 (November 2024). It gives you a choice: run AI models locally on your own hardware, or connect to external providers like OpenAI and DeepL. The key difference from most SaaS tools is that your data stays under your control.

Nextcloud calls this approach "Ethical AI." The project publishes a rating system for each AI backend, grading providers by their data handling, model transparency, and privacy stance. If you choose a local model (Ollama, LocalAI) instead of external APIs, no data leaves your server. If you use an external provider, you see upfront what happens to your files and text.

The AI Assistant integrates into Nextcloud Mail, Talk (video/chat), Photos, and Calendar. You can also use it through a dedicated chat interface. Think of it as ChatGPT inside your file sync tool, with the privacy guarantees you set.

Nextcloud AI Features: What Can It Do?

Nextcloud AI includes seven core capabilities. Understanding what each does helps you decide which backends to enable.

Text generation and chat let you prompt an LLM directly ("summarize this document") or use context chat, which indexes your files and lets the AI answer questions about your own data. Text generation works with Ollama, LocalAI, OpenAI, or Anthropic.

Image generation creates images from text prompts using Stable Diffusion or similar. Image recognition analyzes photos in your Nextcloud Photos library, tagging them automatically. Both require significant local resources if you use local models; external providers offload that cost.

Speech-to-text (transcription) converts audio files or Talk recordings into text. Text-to-speech reads text aloud. Machine translation converts text between languages. These three often come as a bundle: if you enable one, enable all three.

Finally, AI agents let you automate workflows: "Create a summary of all files modified this week and email it to me." Agents combine text generation, file indexing, and task scheduling.

Important: not all backends support all features. Ollama is strong on text and code generation but does not do image generation. LocalAI adds image generation. External APIs usually support everything, but you pay per request.

Local vs External: Where Does Your AI Run?

This is the biggest decision. Local means you run the model on your own server (Ollama or LocalAI). External means you pay a third-party (OpenAI, DeepL, Anthropic, IBM Watsonx) to run it and return the result.

Local AI wins on privacy and compliance. Your training data, file content, and queries never leave your infrastructure. If you operate in a regulated industry (healthcare, finance, law) or have customers in the EU, local keeps you in control of GDPR obligations. No vendor lock-in: you can swap models without renegotiating contracts.

Local AI loses on convenience and cost upfront. You need enough CPU and RAM (or GPU) to host the model. A small model (Llama 2 7B) might run on a 4-core, 8 GB server; a larger one (Mistral 8x7B) needs more. Models also update slowly: you are not getting GPT-4 next week if you run Ollama. Hallucinations (nonsense answers) are more common in smaller open-source models.

External AI wins on capability and simplicity. OpenAI's GPT-4o and Claude 3.5 Sonnet are better at reasoning than any open-source model today. You do not manage servers or worry about model updates. Cost is predictable and often lower per request, especially for occasional use.

External AI loses on privacy and long-term cost. Your files are uploaded to a third party's servers. Even if they promise not to train on your data, they see it. If you use the API hundreds of times a day, costs add up: OpenAI charges $3-$15 per million input tokens. For a 10-person team generating summaries daily, external can cost $200-500/month.

Use a decision matrix: if you need HIPAA/GDPR compliance and have budget for hardware, go local. If you need the best model and can afford the API cost, go external. If you are unsure, start with an external API (lower friction) and migrate to local later.

Hardware Requirements for Local AI

Running AI locally on a Nextcloud server is feasible but constrained. The size of the model and your hardware dictate speed and accuracy.

For text generation, a small model (Ollama's Mistral 7B, Llama 2 7B) needs a server with at least 8 GB of RAM and a modern CPU (4+ cores). It will generate text slowly (5-15 seconds per response) without a GPU. With an NVIDIA GPU (a 4 GB card is minimum, 8+ GB is comfortable), response times drop to 1-3 seconds.

A larger model (13B or 30B parameters) needs 16-24 GB of RAM, or 8-12 GB with a GPU. An 8x7B model (MoE) runs on 16-20 GB of VRAM on a GPU or 48+ GB of CPU RAM. Running these on typical managed servers is not practical.

For image generation and recognition, you need even more: a GPU becomes mandatory. Stable Diffusion XL (SDXL) wants 8 GB of VRAM; smaller versions need 4-6 GB.

For a 10-100 person company, this usually means one of three paths:

Buy a dedicated GPU server ($50-150/month from Hetzner, Scaleway, or Opsily) for local AI inference.
Keep Nextcloud on a modest server and route AI requests to a cheaper external API (no hardware costs).
Use managed Nextcloud hosting that bundles AI (no ops overhead).

Self-hosting local AI is not cost-free. You are trading cash for privacy.

Step-by-Step: Setting Up Nextcloud AI

This is the section that trips up most teams. The steps are straightforward, but there is one critical gotcha: background workers.

First, install the Nextcloud Assistant app from the app store. Log in as an admin, go to Settings > Apps, search for "Assistant," and click "Download and enable."

Next, choose your AI backend. In Settings > Administration > AI (or Settings > AI, depending on your Nextcloud version), you will see options: Ollama, LocalAI, OpenAI, DeepL, Anthropic, or IBM Watsonx. If you are trying local first, install Ollama on another server (or the same server if it has spare capacity). Ollama downloads and caches models automatically.

Here is the gotcha: Nextcloud AI requests are handled by background workers. If workers are not running, your AI requests will timeout or hang indefinitely. This is the #1 reason setups fail.

Background workers run long tasks asynchronously so they do not block the web server. In a default Nextcloud install, they run via cron (every 5 minutes). This is too slow for AI. You need real workers.

Set up one of these:

Nextcloud's built-in web cron: go to Settings > Administration > Background Jobs and select "Webcron." This fires the job queue when anyone visits the site. Fast enough for testing, but unreliable at scale.
System cron (Linux only): add a cron job that calls nextcloud/occ background:cron every minute. Reliable and fast.
Nextcloud daemon (systemd): run nextcloud/occ background:queue:listen as a systemd service. This is best for production: it processes jobs instantly as they arrive.

Without workers, every AI request hangs for 30 seconds and fails. This is not a bug; it is by design. Nextcloud assumes long tasks need a background worker.

Once workers are running, test it: open Settings > AI, select your backend (e.g., Ollama), and type a test prompt into the Assistant chat. If it responds in under 10 seconds, workers are working.

If you chose Ollama, make sure the endpoint uses the correct format: your server address at port 11434, with the path suffix /v1. For example, if your Ollama server is at ollama.local, enter ollama.local:11434/v1. The /v1 suffix is required. Without it, Nextcloud will not recognize the endpoint.

For external APIs, paste your API key into the settings field. OpenAI, DeepL, and others are straightforward: paste the key, and you are done.

Troubleshooting: if AI requests hang for 30+ seconds and then fail, you need workers. If requests fail immediately, check your endpoint URL (especially that /v1 suffix for Ollama) or your API key. If responses are nonsensical or very slow, you may have a small model or low-power hardware; try a smaller model (Llama 2 7B instead of 13B).

Enabling Context Chat & Advanced Features

Once the basic setup works, you can add more power. Context chat is the most useful advanced feature.

Context chat indexes your files so the AI can answer questions about them. "How many hours did we log last month?" The assistant reads your spreadsheets. "What was the decision on the blue-sky project?" It searches your notes.

To enable it, install the "Assistant" app (same as before) and ensure you have Nextcloud's vector database running. This requires PHP 8.1+ and a machine with a few GB of free disk space. The vector database stores embeddings (mathematical representations of document meaning) so searches are fast.

Once enabled, go to Settings > AI > Context. Choose which folders to index. Nextcloud will background-index them. This is where the background workers become critical again: without them, indexing stalls.

AI agents let you set up recurring tasks. Example: "Every Monday, create a summary of all files modified last week and send it to me via email." This combines text generation, file scanning, and email sending. Agents are still experimental; reliability varies.

To use agents, ensure your AI backend supports function calling (most do). Then go to Settings > AI > Agents and create a rule. The UI is minimal: you mostly write prompts telling the agent what to do.

AI on Managed Nextcloud: What Works?

If you use a managed Nextcloud instance (including Opsily's managed hosting), AI support depends on the provider. Not all managed providers enable AI by default because it adds resource overhead and complexity.

Opsily's managed Nextcloud instances support Nextcloud AI. The infrastructure is optimized for AI workloads: we handle background workers automatically, so you do not have to configure them yourself. API credits for external providers (OpenAI, DeepL) can be added to your instance. For local models, we can provision a GPU-equipped server or route requests to Ollama running on a separate machine.

If you use another managed provider, check their documentation or contact support. Some do not offer AI integration at all; they want you to use external APIs only.

Managed hosting removes the infrastructure burden. You do not set up workers or tune hardware. You pay a flat monthly fee instead of per-API-call. This is worth the premium if you are a small team without a DevOps engineer.

Privacy, Compliance & Best Practices

AI and privacy are not mutually exclusive if you choose the right backend.

Local AI (Ollama or LocalAI) keeps everything inside your Nextcloud server. Your documents never leave; neither do your queries. This satisfies GDPR, HIPAA, and other regulations because the data controller (you) remains in possession of all data.

External APIs (OpenAI, DeepL) transmit your data to a third party. Even if they promise not to train on your data, they see it and store it temporarily. OpenAI's API terms say they do not use API calls for model training, but they retain data for 30 days for safety checks. DeepL is more privacy-friendly: they delete translations immediately. Check each provider's terms.

Nextcloud's Ethical AI rating system grades providers on:

Data retention: do they delete your data?
Transparency: do they explain their model and limitations?
Privacy: can you opt out of usage analytics?

Before enabling an external API, read the rating. If you are in a regulated industry, bias toward local or providers with strong privacy ratings.

Best practices: (1) Enable AI for your team; do not deploy it without buy-in. (2) Start with external APIs; they require less infrastructure. (3) Migrate to local models if privacy needs or cost demand it. (4) Disable unused features (image generation is resource-hungry; use only if needed). (5) Monitor API costs; set up billing alerts. (6) Index only necessary folders for context chat; too much data makes searches slow.

Frequently Asked Questions

What is Nextcloud AI Assistant?

Nextcloud AI Assistant is a built-in tool that lets you use language models, image generation, transcription, and translation without leaving Nextcloud. You choose whether to run models locally (Ollama, LocalAI) or use external APIs (OpenAI, DeepL, Anthropic). It is included in Nextcloud Hub.

Can I run Nextcloud AI completely locally and offline?

Yes. Install Ollama or LocalAI on your server, configure Nextcloud to point to it, and enable background workers. Your data never leaves the server. This works best with at least 8-16 GB of RAM or a GPU.

What are the hardware requirements for Nextcloud AI?

For text generation with a small model (7B parameters), you need 8 GB of RAM and a 4+ core CPU. For larger models (13B-30B), 16-24 GB of RAM or a GPU. For image generation, you need a GPU (minimum 4-6 GB VRAM). Larger setups often run AI on a separate GPU server and query it from Nextcloud.

How do I set up Ollama with Nextcloud AI?

Install Ollama on a server and start the service. In Nextcloud Settings > AI, configure the backend to Ollama and set the endpoint to your Ollama server address at port 11434 with the /v1 path suffix (for example, ollama.local:11434/v1). The /v1 suffix is required. Ensure Nextcloud has background workers running.

What is the difference between local AI and external AI providers?

Local AI keeps your data on your server but requires hardware investment and offers slower responses from smaller models. External APIs (OpenAI, DeepL) are faster, higher quality, and require no setup, but your data is uploaded to their servers and you pay per request. Choose based on privacy needs and budget.

How do background workers work in Nextcloud AI?

Workers process long-running tasks asynchronously so they do not freeze the web server. For AI, workers are mandatory: without them, requests timeout. Set up workers using system cron (nextcloud/occ background:cron every minute) or the daemon (nextcloud/occ background:queue:listen).

What AI models does Nextcloud support?

Nextcloud supports any model via Ollama or LocalAI (Mistral, Llama 2, Mixtral, etc.), plus external APIs like OpenAI (GPT-4o, GPT-4 Turbo), Anthropic (Claude), DeepL, and IBM Watsonx. The model list updates as Ollama and LocalAI add new releases.

How do I enable Nextcloud AI context chat?

Install the Assistant app, ensure you have a vector database, then in Settings > AI > Context, choose which folders to index. Nextcloud will embed and index them in the background. Context chat is then available in the Assistant interface and in Nextcloud Mail.

The Bottom Line

Nextcloud AI is a real privacy-first alternative to ChatGPT. It works offline, keeps your data on your server, and integrates into the tools your team already uses. Setup is straightforward once you understand background workers and choose your backend (local or external). For a small team without a DevOps expert, external APIs are simpler. For teams with compliance requirements or heavy AI use, local models or managed Nextcloud hosting make sense. If you want AI without managing the infrastructure, Opsily's managed Nextcloud instances handle everything: start a free trial at the console.

Nextcloud AI: A Complete Setup and Feature Guide