Dify tutorial: what it is, how to run it and your first app

What Dify is

Dify is open source, and it lets you assemble apps that call large language models (LLMs), the kind of model behind ChatGPT and Claude. You put an app together on a visual canvas where each step is a block called a node, then publish it as a web page, an API or a chat widget on your own site.

The README lists seven parts. There is a workflow canvas, support for hundreds of proprietary and open-source models, and a Prompt IDE for writing and comparing prompts. The rest are a RAG pipeline, agents that work in a sandbox of their own, LLMOps tools for watching logs and performance, and an API for every feature. RAG, retrieval-augmented generation, means the app looks up passages in your own documents and hands them to the model with the question. The RAG tutorial builds one from scratch in Python.

Studio is the part of Dify where you build. A Workflow runs once from start to finish and returns a result. A Chatflow adds a conversation, so each message runs the flow before a reply goes out. The docs call Workflow the basis for every other app type.

Cloud, self-hosted or Enterprise

Dify comes in three editions. Dify Cloud is hosted by LangGenius, the company behind Dify. The Community Edition is the self-hosted one, and the Deploy Dify page says it runs anywhere Docker runs: a laptop, an on-premises server or a cloud VM. Dify Enterprise adds single sign-on (SSO), role-based access control (RBAC) and support agreements for organizations that host Dify themselves.

A new Cloud account starts on the Sandbox plan with 200 AI credits for calling models from providers such as OpenAI, Anthropic and Gemini. The quick start says the credits are a one-time allocation that does not renew. Self-hosted, you add a model provider and its API key yourself, because every Dify app needs at least one provider.

The licence has two conditions

The repository carries the Dify Open Source License, which is Apache 2.0 with extra conditions. The file says Dify may be used commercially, including as a backend for other applications, until one of two conditions applies. Then a commercial licence from LangGenius is required.

Unless LangGenius authorizes it in writing, you may not use the source code to run a multi-tenant environment, and one tenant means one workspace. That is the first condition. The second concerns the logo: when you use Dify's frontend, you may not remove or change the logo or copyright information in the console or apps. The frontend is the web/ folder, or the web image in Docker, and the rule does not cover uses that skip it.

A company that gives each customer a workspace on a Dify it hosts is the case the first condition describes. Ask LangGenius or a lawyer before you build that, because a summary here is no substitute for the file.

Run Dify on your own machine

The Docker Compose setup bundles PostgreSQL, the Weaviate vector database and the other services Dify needs, so there is no database to prepare first. You need Docker with Docker Compose, Git and OpenSSL. On macOS, give Docker Desktop's virtual machine at least 2 virtual CPUs and 8 GiB of memory. On Windows, use Docker Desktop with WSL 2 and keep the source code in the Linux file system. If Docker is new to you, the n8n self-hosting lesson shows where to get it.

docker compose version
git clone --branch <version> --depth 1 https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
openssl rand -hex 32
# paste the output into .env as DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN
docker compose up -d
docker compose ps --all

1. Run docker compose version and check that it reports 2.35.0 or later.
2. Pick a tag on the Dify releases page. Clone it with git clone --branch followed by the tag, --depth 1 and the repository address, then move into dify/docker.
3. Copy the template with cp .env.example .env.
4. Make a token with openssl rand -hex 32 and set it in .env as DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN. Leave COMPOSE_PROFILES at its default.
5. Start the services with docker compose up -d, then run docker compose ps --all. Long-running services should show Up or healthy. The one-time init_permissions task shows Exited (0) when it is done, which is expected.
6. Open http://localhost/install, create the administrator account and sign in at http://localhost. If port 80 is taken, set EXPOSE_NGINX_PORT in docker/.env to another port.

Before anyone else can reach the install, set up HTTPS and replace the bundled development credentials in docker/.env. That covers the database and Redis passwords, the code sandbox keys, the Weaviate key, the plugin daemon keys and the agent tokens. After a change to .env, run docker compose up -d, because docker compose restart keeps the old environment.

Build a first chatbot

Connect a model first. In Integrations > Model Provider, install a provider such as OpenAI, click Add API Key on its card and enter the key. On Cloud, the Sandbox credits cover supported models once the provider is installed, with no key. Then click Default Models at the top right and set the System Reasoning Model, which every node without a model of its own falls back on. When a default is empty, the features that rely on it stop working.

The chatbot below is the docs' own beginner example, split there into three steps of 2, 6 and 3 minutes. It finds the country in a question, answers it and adds a fun fact that a Code node looks up. This is the system prompt for its LLM node, copied from the Simple Chatbot page.

The user will ask a question about a country. The question is {{sys.query}}
Tasks:
1. Identify the country mentioned.
2. Rephrase the question clearly.
3. Answer the question using general knowledge.
Respond in the following JSON format:
{
  "country": "<country name>",
  "question": "<rephrased question>",
  "answer": "<direct answer to the question>"
}

1. Go to Studio > Workflow > Create from Blank > Orchestrate > New Chatflow > Create, as the tutorial words it.
2. Add an LLM node with Add Node and connect it to the start node. Choose a default model and paste the prompt above. Type { or / in a field to pick a variable.
3. Under Output Variables, switch Structured on, click Configure and choose Import from JSON. Paste a schema that gives country, question and answer the type string. Structured output is what lets the next node read country on its own.
4. Add a Code node after the LLM node. Rename one input variable to country and set it to structured_output > country. Paste the Python from the next section and rename the output variable result to fun_fact.
5. Add an Answer node with three lines: Q: {{ structured_output.question }}, A: {{ structured_output.answer }} and Fun Fact: {{ fun_fact }}.
6. Click Preview and ask one of the tutorial's questions, such as "What is the capital of France?" or "Describe the culture in Italy".

The function behind the fun fact

A Code node runs Python or JavaScript inside a sandbox. Its function takes the input variables you declare and has to return a dictionary whose keys are the output variables you declared, here fun_fact. The three countries in the dictionary are the tutorial's sample data. For any other country the function returns the fallback line that starts "No fun fact available for".

def main(country: str) -> dict:
  country_name = country.lower()
  fun_facts = {
    "japan": "Japan has more than 5 million vending machines.",
    "france": "France is the most visited country in the world.",
    "italy": "Italy has more UNESCO World Heritage sites than any other country."
  }
  fun_fact = fun_facts.get(country_name, f"No fun fact available for {country.title()}.")
  return {"fun_fact": fun_fact}

Dify changes fast, so match the page to your version

A tutorial written for an older release can show screens that have moved. Dify publishes releases on GitHub with tags such as 1.19.0, dated 4 November 2026. These releases changed parts this course covers.

For an existing self-hosted install, the Docker Compose page says to read the target release's upgrade guide first and to keep your own .env.

Common mistakes

• Starting the stack without the sandbox token. The agent backend and its local sandbox need DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN in docker/.env, and they keep restarting without it.
• Reading init_permissions with Exited (0) as a failure. It is a one-time task that prepares storage permissions.
• Editing .env and then running docker compose restart. Restart keeps the containers' old environment, so use docker compose up -d.
• Opening localhost for a server that runs elsewhere. For a remote deployment, use the server's IP address or domain.
• Leaving the bundled development passwords on a machine other people can reach.
• Starting an app before a model provider is connected, so the LLM node has nothing to call.

Try it yourself

• Ask the chatbot about a country the dictionary does not hold, and read the fallback line it returns.
• Add a fourth country to the dictionary in the Code node and preview again.
• Change the model on the LLM node, or its Temperature, which runs from 0 for the most predictable replies to 1 for the most varied, and compare two answers to the same question.

Next

Lesson 2 builds a workflow with branches, variables and the tools for debugging a run. The best AI agent builder guide compares other tools for building agents, such as n8n, Zapier and Make, if you want to see those first.

Frequently asked questions

Sources

1. Dify on GitHub: README (read November 6, 2026)https://github.com/langgenius/dify/blob/main/README.md
2. Dify on GitHub: LICENSE (read November 6, 2026)https://github.com/langgenius/dify/blob/main/LICENSE
3. Dify Docs: Deploy Dify with Docker Compose (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/quick-start/docker-compose.mdx
4. Dify Docs: Deploy Dify (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/deploy/overview.mdx
5. Dify Docs: 30-Minute Quick Start (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/quick-start.mdx
6. Dify Docs: Simple Chatbot (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/learn/tutorials/simple-chatbot.mdx
7. Dify Docs: Key Concepts (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/learn/key-concepts.mdx
8. Dify Docs: Workflow & Chatflow (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/workflow-chatflow.mdx
9. Dify Docs: LLM node (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/llm.mdx
10. Dify Docs: Code node (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/nodes/code.mdx
11. Dify Docs: New Agent overview (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/overview.mdx
12. Dify Docs: Build a new Agent (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/build/new-agent/build.mdx
13. Dify Docs: Model Providers (read November 6, 2026)https://github.com/langgenius/dify-docs/blob/main/en/self-host/use-dify/workspace/model-providers.mdx
14. Dify releases on GitHub (read November 6, 2026)https://github.com/langgenius/dify/releases
15. Dify on YouTube: Dify Quickstart Guide: Build Your First AI Workflow (read November 6, 2026)https://www.youtube.com/watch?v=dJ34OU_JY7Y