How to Install and Use Dify.ai: The Complete Entry Tutorial for Self-Hosted AI Agents

Introduction: Why Learn Dify.ai

Dify.ai is the open-source answer to ‘how do we build AI apps without vendor lock-in?’ The platform gives you everything commercial alternatives offer – visual builder, RAG, agents, observability – while keeping your data, models, and code on infrastructure you control. For teams that need to own their AI stack, Dify is the path of least resistance.

This guide walks you from Docker install to deployed production AI apps. We’ll cover setup, model configuration, your first app, RAG and knowledge bases, agent mode, tools, workflows, and the patterns teams use in production. By the end, you’ll have a working AI app and the knowledge to build dozens more.

Part 1: Prerequisites

You need: a Linux, Mac, or Windows machine with Docker installed; 8GB+ RAM (16GB recommended for RAG); API keys for at least one LLM provider (OpenAI, Anthropic, or local via Ollama). For production: a VPS or cloud VM with at least 4 vCPU and 16GB RAM.

• Docker Desktop (Mac/Windows) or Docker Engine (Linux)
• docker-compose v2 (included in Docker Desktop)
• Git
• 8-16GB RAM for dev, 16-32GB for prod
• At least one LLM API key (OpenAI / Anthropic / Google / etc.)

Part 2: Installing Dify with Docker

Clone the repo and start the stack:

git clone https://github.com/langgenius/dify
cd dify/docker
cp .env.example .env
docker compose up -d

Docker pulls images (first run takes 5-10 min), starts services, and binds to localhost. Check status with `docker compose ps` – you should see 8-10 containers running.

Firewall and ports

Dify binds port 80 and 443 by default. If those are in use or blocked, edit .env to change DIFY_WEB_PORT and DIFY_API_PORT. For production, always put Dify behind a reverse proxy (Nginx, Caddy) with SSL.

Part 3: First Login

Open http://localhost. First visit prompts you to create an admin account. Use a strong password – this is the root admin for your Dify instance. After login, you land on the Studio home page with options to create apps.

Part 4: Configuring Model Providers

Go to Settings > Model Providers. Add providers you’ll use. For OpenAI: paste your API key; Dify lists available models. For Anthropic: same flow with ANTHROPIC_API_KEY. For local Ollama: configure the endpoint URL. For Azure OpenAI: enter resource, deployment, and key. Dify supports 30+ providers out of the box.

• OpenAI: GPT-4o, GPT-5, o1, o3
• Anthropic: Claude Sonnet 4.6, Opus 4.7, Haiku
• Google: Gemini 2.5 Pro, Flash
• Azure OpenAI: any deployed model
• Local: Ollama (llama3, mistral, qwen, etc.)
• Others: Mistral, Groq, OpenRouter, Replicate, and more

Part 5: Your First App – Chatbot

From Studio, click ‘Create from blank.’ Choose ‘Chatbot’ and ‘Basic.’ Name it ‘My First Assistant,’ select a model (GPT-4o is a safe starting choice), and click Create. You land in the app editor. Test in the right-side preview – ask a question, see the response.

Configuring the chatbot

Edit the ‘Prompt’ field to shape the assistant’s behavior. Set temperature (0.3 for focused, 0.7 for creative). Add opening remarks that greet new users. Save and test.

Part 6: Adding a Knowledge Base (RAG)

Go to ‘Knowledge’ in the main nav. Click ‘Create Knowledge.’ Upload PDFs, Word docs, Markdown, or connect Notion/web URLs. Dify chunks, embeds, and indexes the content automatically. Embeddings run through your configured provider (OpenAI text-embedding-3 is standard).

Back in your chatbot, add the knowledge base via ‘Context’ settings. Now the chatbot answers grounded in your documents with citations.

• Upload: PDFs, Word, Markdown, CSV, Excel
• Connect: Notion, Confluence, web URLs
• Chunking: automatic or custom (paragraphs, sentences, fixed)
• Embedding: configurable per knowledge base
• Retrieval: top-K + similarity threshold

Part 7: Agent Mode

For apps that need to take actions (not just answer), switch to Agent type. Create from blank > Agent. Configure:
– Model: use a reasoning-strong model (GPT-4o, Claude Opus, o3)
– Tools: add the tools your agent can use
– Instructions: clear role and goal

Agent mode enables the model to autonomously call tools, chain reasoning, and deliver outcomes – not just responses.

Part 8: Tools and Plugins

Dify has a growing tool library and supports custom plugins. Built-in tools:
– Web Search (Google, DuckDuckGo, Tavily)
– Calculator
– Current Time
– Image Generation (DALL-E, Stable Diffusion)
– Code Interpreter
– HTTP Request (call any API)
– Custom API (wrap your own endpoints)

For full customization, write a plugin in Python or use the OpenAPI Schema tool to import any OpenAPI-described service.

Part 9: Workflow / Chatflow

For complex logic, use Workflow (for one-shot apps) or Chatflow (for multi-turn chat with branching). These let you drag-and-drop a flow: LLM call -> condition -> different actions -> output. Example: a customer service app that classifies the query, then routes to FAQ lookup or human escalation.

Part 10: Deploying to Users

Every Dify app has three delivery options: Embedded chat widget (JS snippet for your website), Public chat URL (shareable link), API endpoint (programmatic access). For production: configure custom domain, SSL via reverse proxy, and rate limiting.

• Embed: paste the JS snippet on your site
• Public link: share with anyone via URL
• API: integrate into your own apps
• Teams and SSO: enterprise tier only

Part 11: Observability and LLMOps

Go to an app > Logs. See every conversation, token usage, latency, and model used. Filter by user, time range, or quality markers. For A/B testing, run two prompt variants and compare metrics over time. For production, set up alerts for cost spikes, latency issues, or error rates.

Part 12: Production Hardening

Before scaling Dify to real users: 1) Put behind HTTPS reverse proxy (Nginx/Caddy); 2) Use managed Postgres instead of containerized (easier backup); 3) Move vector DB to managed Qdrant/Weaviate if scale demands; 4) Set rate limits per user; 5) Add monitoring (Prometheus + Grafana); 6) Back up .env and data volumes on a schedule; 7) Upgrade Dify via git pull + docker compose up.

Upgrade path

Dify ships releases frequently. Subscribe to GitHub releases. For production, test upgrades on staging first. Never pull main in production – always upgrade to tagged releases.

30 Pro Tips and Tricks

These are the details that separate beginners from pros. Skim them, apply the ones that click, and come back to the others as you level up.

1. Use Docker for development and initial production – move to Kubernetes only if scale demands.
2. Keep .env file in a secure secrets manager, not in git.
3. Pin Dify versions in docker-compose – don’t track main.
4. For high-volume apps, separate the vector DB from Dify’s default Postgres.
5. Use Ollama for local dev to avoid API costs.
6. Configure model providers once; reuse across all apps.
7. Start with chatbot before agent – simpler to debug.
8. Keep prompts in Dify’s prompt editor, not in code – easier iteration.
9. Use knowledge bases for factual grounding; don’t rely on generic LLM memory.
10. Chunk knowledge thoughtfully – too small loses context, too large hits limits.
11. Monitor retrieval hit rates – poor retrieval = poor answers.
12. Set reasonable temperature per use case (0.3 for facts, 0.7 for creative).
13. Enable logs from day one – you’ll want the history.
14. For agent apps, limit tool use count per turn to prevent runaway loops.
15. Use workflow apps for structured tasks; chat apps for open-ended conversation.
16. Version prompts by duplicating apps when experimenting.
17. Test with low-token-cost models during dev; switch to production model at the end.
18. For regulated industries, self-host and keep data in your VPC.
19. For MVP, start on Dify Cloud to validate before self-hosting.
20. Use Dify’s API keys for programmatic integration – don’t share user accounts.
21. Keep a staging instance to test Dify upgrades before production.
22. Join Dify’s Discord for fast help on specific issues.
23. Contribute upstream if you build reusable tools – helps the whole community.
24. Budget for storage – vector DBs grow with knowledge bases.
25. Use Dify’s built-in eval tools to check prompt quality over time.

App Configuration Templates

Five working Dify app configurations. Adapt prompts and knowledge to your domain.

Customer support chatbot

Type: Chatbot. Model: GPT-4o. Temperature: 0.3. Prompt: ‘You are a customer support agent for [company]. Answer only based on the knowledge base. If you do not know, offer to connect to a human.’ Knowledge: uploaded FAQ docs + product docs. Opening: ‘Hi! How can I help today?’

Research agent

Type: Agent. Model: Claude Opus 4.7. Tools: web search, HTTP request, code interpreter. Prompt: ‘You are a research analyst. Gather facts, cite sources, and produce structured briefs. Prefer primary sources.’ Max iterations: 15.

Content summarizer

Type: Workflow. Nodes: HTTP Request (fetch URL) -> LLM (summarize in 200 words) -> LLM (extract key quotes) -> Output (formatted markdown). Great for reading long articles quickly.

SQL assistant

Type: Chatbot with code tool. Model: GPT-4o. Prompt: ‘You convert English questions into SQL queries for our schema: [paste schema]. Always explain your reasoning. Offer safer alternatives for destructive operations.’

Multilingual support

Type: Chatflow. Nodes: Classify language -> route to correct knowledge base -> respond in user’s language. Knowledge: separate KB per language for best grounding.

Integration With Other AI Tools

Dify.ai’s open architecture means it plays with almost anything. Native: any LLM via API, Ollama for local models, Postgres/Redis as core services, Qdrant/Weaviate/pgvector for vectors. Via tools: any REST API, any OpenAPI-described service, custom Python plugins. Via Dify API: integrate AI apps into your own products with a single HTTP call. For monitoring: export logs to Datadog/Prometheus. For auth: SSO via Enterprise Edition. For frontend: Dify’s embedded widget drops into any website; or build custom UIs calling Dify’s API. The reference self-hosted AI stack in 2026: Dify for app layer, Ollama for dev models + OpenAI/Anthropic for production, Qdrant for vectors, Postgres for state, Nginx for reverse proxy, Prometheus + Grafana for monitoring, and Docker Compose tying it all together.

Industry-Specific Use Cases

This tool shows up differently across industries. These six sectors are where it is having the largest impact in 2026.

Regulated Industries (Healthcare, Finance)

Healthcare providers and financial services firms use self-hosted Dify to build AI apps that never send data to commercial APIs – keeping patient/customer data inside compliance boundaries.

Government and Defense

Agencies deploy Dify on-premise for internal AI assistants that must operate in air-gapped or highly restricted environments.

Mid-Market Software Companies

SaaS companies embed Dify-powered AI features into their products without building AI infrastructure from scratch.

Enterprise R&D

Innovation teams prototype and pilot AI agents in Dify before deciding what to productize or build from scratch.

AI Solution Providers and Agencies

Agencies white-label Dify to deliver custom AI apps to SMB clients at price points commercial platforms can’t match.

Academic and Research

Universities self-host Dify for courses, research projects, and experiments – students and researchers get production-grade tools without subscription costs.

Troubleshooting Guide

Here are the most common issues and the fastest fixes.

Docker containers fail to start

Check logs: `docker compose logs -f`. Most common: port conflicts (80/443), insufficient memory, or corrupted .env. Verify all required env vars are set.

Model provider connection fails

Verify API key is valid. For self-hosted models, confirm the endpoint URL is reachable from Dify’s containers (Docker network, not localhost).

Knowledge base returns poor answers

Check chunking settings – try smaller or larger chunks. Verify embedding model is appropriate for your content language. Check retrieval top-K (increase if answers are missing context).

Agent loops or times out

Set max iterations on the agent. Simplify the prompt. Reduce number of tools. Make tool descriptions clearer so agent chooses correctly.

Upgrading broke something

Always read release notes before upgrading. Test in staging. Dify has occasional breaking changes; pin versions and upgrade deliberately.

Performance issues under load

Scale Postgres (managed). Move vector DB to managed Qdrant. Add Redis cluster for caching. Put Nginx in front of the Dify API for better concurrency.

Your 90-Day Mastery Plan

Mastery does not come from reading guides – it comes from deliberate practice. Here is a 90-day plan focused on self-hosted setup, multi-model orchestration, and production deployment:

Days 1-7: Foundations

Sign up, explore every menu, and produce ten generations or test runs. Focus on fluency with the interface. By day 7, you should feel comfortable navigating without hunting for buttons.

Days 8-30: Skill Building

Pick one real project and commit to shipping it. Iterate every day. By day 30, you have one real piece of work in the world and a set of personal rules for when this tool works best.

Days 31-60: Systematization

Build repeatable workflows. Save prompt templates, configure defaults, set up integrations with other tools. Document your personal playbook. Ship at least 10 more finished pieces.

Days 61-90: Scale and Monetization

Turn your skill into output that pays. Productize your workflow – sell a service, take on client work, or build a content business around it. By day 90, this tool is no longer something you are learning – it is something you are profiting from.

The difference between people who experiment with AI tools and people who build careers on them is simply showing up every day for 90 days. Most quit after two weeks. The ones who stay compound faster than anyone expects.

Real-World Case Studies

Here are three real-world examples showing how this tool is being used right now.

The Healthcare System Internal Assistant

A 500-provider healthcare network self-hosts Dify to power an internal clinical reference assistant. Doctors query drug interactions, treatment guidelines, and protocols – all grounded in the system’s own clinical knowledge base. No patient data leaves the network. 40,000 queries/month, saving an estimated 3,000 clinician hours annually.

The DTC Brand Customer Support

A $20M DTC brand built a Dify chatbot handling 70% of customer support tickets. Order status, returns, product questions – all answered grounded in Shopify data and FAQ docs. Support team reduced from 6 to 2 people while customer satisfaction scores rose. Total infrastructure cost: $180/month.

The AI Agency White-Label

A 12-person AI agency uses Dify Enterprise to deliver custom AI apps to 40 SMB clients. Each client gets a branded Dify instance with their own apps. Agency bills $2,000-$10,000/month per client. Agency revenue grew 4x in 18 months leveraging Dify as the delivery platform.

Beyond the Basics

Once you have a handful of apps running, these patterns unlock the next level of Dify capability.

Chaining Apps

Apps can call other apps via the API, enabling composition. A top-level ‘customer assistant’ app might call a ‘product lookup’ app and a ‘support ticket’ app as sub-services. This keeps each app focused and testable.

Custom Plugins

For integrations beyond Dify’s built-in tools, write Python plugins. The Dify plugin SDK lets you wrap any service as an agent-callable tool. Publish plugins internally for team reuse or open-source them for the Dify community.

Multi-Tenant Deployments

For agencies or SaaS companies, Dify supports multi-workspace architecture where each client gets an isolated workspace. Automate provisioning via the API for new customer onboarding.

Advanced RAG Patterns

Beyond basic document upload, use Dify’s hybrid search (keyword + semantic), rerank with cross-encoders, and parent-child chunking for better retrieval on structured documents. Evaluate retrieval quality with Dify’s built-in eval tools.

Production Monitoring

Export logs to Datadog or Grafana. Set alerts for error rate spikes, cost anomalies, and latency regressions. For regulated workloads, enable audit logging and route logs to a SIEM.

Frequently Asked Questions

Is Dify really free?

Yes, the open-source version is MIT-licensed and free forever. Your only costs are infrastructure (a VPS is $20-200/month depending on scale) and LLM API usage. Dify Cloud and Enterprise are paid upgrades for managed service.

How does Dify compare to LangChain?

LangChain is a Python library. Dify is a full platform. LangChain gives more low-level control; Dify gives faster time-to-production. Many teams use both – LangChain for custom logic, Dify for deployment/observability.

Do I need to be a developer to use Dify?

Basic dev skills help for setup and customization, but non-developers can build apps in the visual interface. DevOps skills (Docker, Linux basics) are needed for self-hosting.

Can I use Dify for commercial products?

Yes. MIT license allows commercial use. You can build and sell products on top of Dify. Check current license terms for details on attribution requirements.

How secure is self-hosted Dify?

As secure as you make your infrastructure. Standard WordPress-level security practices apply: HTTPS, auth hardening, regular updates, network segmentation. No data leaves your infrastructure unless you configure external model providers.

What models work best with Dify?

GPT-4o, Claude Sonnet 4.6, and Claude Opus 4.7 for production. GPT-4o-mini and Claude Haiku for cost-sensitive apps. Local Ollama models (Llama 3, Qwen) for dev or privacy-critical deployments.

How do I back up my Dify instance?

Back up the Postgres database (primary state), the .env file (configuration), and any uploaded knowledge files (in the data volume). Automate with cron. Test restore quarterly.

Can I integrate Dify with my existing app?

Yes via the Dify API. Call endpoints to run chatbots, agents, or workflows programmatically. Response streaming supported. Most teams build a thin Dify API integration layer in their own backend.

How fast can I get to production?

An MVP chatbot or internal tool: 1-2 weeks. A polished customer-facing app with RAG: 3-6 weeks. Large enterprise rollout with governance: 2-4 months. Much faster than building from scratch.

What happens if Dify (the company) shuts down?

The open-source version keeps running – it’s MIT licensed. You own your data and your deployment. This is the fundamental advantage of open-source platforms: no vendor lock-in risk.

Final Thoughts

Dify.ai is the open-source platform that gives serious teams a credible path to production AI agents without vendor lock-in. The combination of visual builder, RAG, agents, and observability in one self-hostable package is genuinely rare in 2026 – most alternatives are either too low-level (frameworks) or too locked-in (commercial SaaS). For teams with basic DevOps capability, Dify removes the hardest parts of shipping AI apps while keeping you in control of your data, models, and economics. Install it today – the hello-world is one Docker command away, and the first real app ships within a few hours.