Self-hosted AI starter kit

April 17, 2026 · View on GitHub

Self-hosted AI Starter Kit is an open-source Docker Compose template designed to swiftly initialize a comprehensive local AI and low-code development environment.

n8n.io - Screenshot

Curated by https://github.com/n8n-io, it combines the self-hosted n8n platform with a curated list of compatible AI products and components to quickly get started with building self-hosted AI workflows.

Tip

Read the announcement

🤖 For AI Agents: START HERE

Mandatory: Every agent working on this project must read these documents in order before starting any tasks.

  1. AGENT_QUICKSTART.md — 5-minute onboarding (sets expectations, tools, ContextStream session setup)
  2. SETUP_STATUS.md — Current phase & immediate next steps (know what's done, what's pending, what's blocked)
  3. multi-agent-workflow.instructions.md — 5-phase pipeline reference (understand orchestration, git worktrees, automatic commits, PR workflow, ContextStream persistence)
  4. initial-setup.instructions.md — Bootstrap guide (Phase 1 setup, git configuration, Docker stack verification)

Multi-Agent Development Framework

This project uses isolated git worktrees and coordinated agent orchestration for parallel AI-driven development:

  • Isolation: Each agent works in its own branch (e.g., feature/agent-foo) with independent git worktree
  • Parallel Work: Multiple agents can work simultaneously without conflicts
  • Automatic Coordination: multi-agent-orchestrator.agent.md auto-detects completed work, creates PRs, merges on approval
  • Code Gating: migration-analyst.agent.md gates all external code integration with security/quality analysis
  • Persistent Memory: All agent decisions and state persisted across sessions via ContextStream

How It Works

Agent creates worktree → Makes changes → Tests pass → Commits & pushes
    ↓
Orchestrator detects new commits → Creates draft PR → Requests reviews
    ↓
Reviews approved → Orchestrator auto-merges → All agents sync to latest main
    ↓
Migration-analyst verifies any migration/ code before final approval
    ↓
Next agent task ready | ContextStream persists entire workflow history

Proactive Documentation Directives

Agents must follow these rules or face auto-rejection:

What’s included

✅ Self-hosted n8n - Low-code platform with over 400 integrations and advanced AI components

✅ Ollama - Cross-platform LLM platform to install and run the latest local LLMs

✅ Qdrant - Open-source, high performance vector store with an comprehensive API

✅ PostgreSQL - Workhorse of the Data Engineering world, handles large amounts of data safely.

What you can build

⭐️ AI Agents for scheduling appointments

⭐️ Summarize Company PDFs securely without data leaks

⭐️ Smarter Slack Bots for enhanced company communications and IT operations

⭐️ Private Financial Document Analysis at minimal cost

Installation

Cloning the Repository

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env # you should update secrets and passwords inside

Running n8n using Docker Compose

For Nvidia GPU users

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env # you should update secrets and passwords inside
docker compose --profile gpu-nvidia up

Note

If you have not used your Nvidia GPU with Docker before, please follow the Ollama Docker instructions.

For AMD GPU users on Linux

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env # you should update secrets and passwords inside
docker compose --profile gpu-amd up

For Mac / Apple Silicon users

If you’re using a Mac with an M1 or newer processor, you can't expose your GPU to the Docker instance, unfortunately. There are two options in this case:

  1. Run the starter kit fully on CPU, like in the section "For everyone else" below
  2. Run Ollama on your Mac for faster inference, and connect to that from the n8n instance

If you want to run Ollama on your mac, check the Ollama homepage for installation instructions, and run the starter kit as follows:

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env # you should update secrets and passwords inside
docker compose up
For Mac users running OLLAMA locally

If you're running OLLAMA locally on your Mac (not in Docker), you need to modify the OLLAMA_HOST environment variable

  1. Set OLLAMA_HOST to host.docker.internal:11434 in your .env file.

  2. Additionally, after you see "Editor is now accessible via: http://localhost:5678/":

    1. Head to http://localhost:5678/home/credentials
    2. Click on "Local Ollama service"
    3. Change the base URL to "http://host.docker.internal:11434/"

For everyone else

git clone https://github.com/n8n-io/self-hosted-ai-starter-kit.git
cd self-hosted-ai-starter-kit
cp .env.example .env # you should update secrets and passwords inside
docker compose --profile cpu up

⚡️ Quick start and usage

The core of the Self-hosted AI Starter Kit is a Docker Compose file, pre-configured with network and storage settings, minimizing the need for additional installations. After completing the installation steps above, simply follow the steps below to get started.

  1. Open http://localhost:5678/ in your browser to set up n8n. You’ll only have to do this once.
  2. Open the included workflow: http://localhost:5678/workflow/srOnR8PAY3u4RSwb
  3. Click the Chat button at the bottom of the canvas, to start running the workflow.
  4. If this is the first time you’re running the workflow, you may need to wait until Ollama finishes downloading Llama3.2. You can inspect the docker console logs to check on the progress.

To open n8n at any time, visit http://localhost:5678/ in your browser.

With your n8n instance, you’ll have access to over 400 integrations and a suite of basic and advanced AI nodes such as AI Agent, Text classifier, and Information Extractor nodes. To keep everything local, just remember to use the Ollama node for your language model and Qdrant as your vector store.

Note

This starter kit is designed to help you get started with self-hosted AI workflows. While it’s not fully optimized for production environments, it combines robust components that work well together for proof-of-concept projects. You can customize it to meet your specific needs

Upgrading

docker compose --profile gpu-nvidia pull
docker compose create && docker compose --profile gpu-nvidia up

docker compose pull
docker compose create && docker compose up

docker compose --profile cpu pull
docker compose create && docker compose --profile cpu up

n8n is full of useful content for getting started quickly with its AI concepts and nodes. If you run into an issue, go to support.

🎥 Video walkthrough

🛍️ More AI templates

For more AI workflow ideas, visit the official n8n AI template gallery. From each workflow, select the Use workflow button to automatically import the workflow into your local n8n instance.

Learn AI key concepts

Local AI templates

Tips & tricks

Accessing local files

The self-hosted AI starter kit will create a shared folder (by default, located in the same directory) which is mounted to the n8n container and allows n8n to access files on disk. This folder within the n8n container is located at /data/shared -- this is the path you’ll need to use in nodes that interact with the local filesystem.

Nodes that interact with the local filesystem

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

💬 Support

Join the conversation in the n8n Forum, where you can:

  • Share Your Work: Show off what you’ve built with n8n and inspire others in the community.
  • Ask Questions: Whether you’re just getting started or you’re a seasoned pro, the community and our team are ready to support with any challenges.
  • Propose Ideas: Have an idea for a feature or improvement? Let us know! We’re always eager to hear what you’d like to see next.

🚀 Codespace Automation — What's been added

This fork extends the original starter kit with automated DevOps scaffolding designed for vibe-coding — you don't need to remember commands; scripts handle the routine work for you.

Auto-installed when you open this Codespace

WhatHow to use
Memory guard daemonStarts automatically — watches RAM, prunes Docker when memory is low
Python 3.12 + uvReady to use: uv run python ...
Node 20 + npmReady to use: npm install / npm test
23 VSCode extensionsCopilot, GitLens, ShellCheck, REST Client, Ruff, Prettier — installed on first open
Git hooksAuto-runs format checks on commit

Scripts you can run anytime

# Check everything is healthy (Docker, ports, RAM, toolchain)
bash .devcontainer/scripts/health-check.sh

# Auto-fix missing dependencies, secrets, venvs, Docker images
bash .devcontainer/scripts/self-heal-deps.sh

# Interactively configure LLM providers (OpenAI, Anthropic, Gemini, OpenRouter)
bash .devcontainer/scripts/setup-llm.sh

# Run all tests across npm and Python sub-projects
bash scripts/test-runner.sh

# Run only Python tests (fast, no LLM API keys needed)
bash scripts/test-runner.sh --suite python --fast

# Install Blackbox CLI (AI coding assistant)
npm run install:blackbox

LLM providers — Ollama works out of the box

The llm.config.json file lists all supported providers. Ollama runs locally inside Docker (no API key needed). To enable cloud providers:

  1. Run bash .devcontainer/scripts/setup-llm.sh — it will prompt you for keys
  2. Or add keys to .env manually: OPENAI_API_KEY=sk-...
  3. Restart the stack: docker compose --profile cpu down && docker compose --profile cpu up -d

🖥️ Shadcn Codespace Dashboard (Foundation)

A Shadcn/UI-based dashboard skeleton has been added at ui/shadcn-dashboard/ to serve as the foundation for a future Codespace VM status & capacity panel.

What's included now:

  • Vite + React + Tailwind CSS + shadcn/ui project skeleton
  • Placeholder "Codespace Status" page with mocked RAM, disk, Docker, and service-health metrics (all clearly marked as mock data)
  • Sidebar navigation shell
  • Full inline TODO markers showing exactly where real metrics will be wired

What's NOT built yet (intentional):

  • Live metric fetching (no backend API yet)
  • Working action buttons (disabled, pending API)
  • Auth / access control

To run the dashboard inside your Codespace:

cd ui/shadcn-dashboard
npm install
npm run dev
# → Open port 5173 in your Codespace Ports tab

Shadcn upstream resources referenced and documented in the dashboard:

📖 Full agent/developer guide: docs/shadcn-dashboard-foundation.md

🧭 Next Steps — What to do after opening your Codespace

Step 1 — Start the AI stack

docker compose --profile cpu up -d
# Wait ~60 seconds, then:
bash .devcontainer/scripts/health-check.sh

Open n8n at http://localhost:5678 and complete the one-time setup wizard.

Step 2 — Set up Codespaces Secrets (replaces .env for shared use)

For any API keys you use regularly, store them as Codespaces secrets so they are automatically available every time you open a codespace — no need to re-enter them:

  1. Go to github.com → Settings → Codespaces → Secrets
  2. Add: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY (whichever you use)
  3. To make them available in the container, add each secret name to the remoteEnv block in .devcontainer/devcontainer.json, e.g. "OPENAI_API_KEY": "${localEnv:OPENAI_API_KEY}"

Step 3 — Connect GitLab CI/CD

This repo includes a .gitlab-ci.yml pipeline. If you want automated pipelines on GitLab (useful for teams or if you want a second CI provider):

➡️ See GITLAB_SETUP.md for a beginner-friendly walkthrough.

Key steps (takes ~15 minutes):

  • Create a GitLab account at gitlab.com
  • Import this GitHub repo into GitLab (New project → Import → GitHub)
  • Enable auto-mirroring (GitLab pulls from GitHub every 5 minutes)
  • Add your secrets as CI/CD Variables in GitLab Settings
  • Set up a weekly schedule for dependency audits

Step 4 — Try GenerateAgents.md (auto-generates AGENTS.md for any repo)

cd GenerateAgents.md
uv sync --extra dev
# Analyze this repo (uses Ollama by default — no API key needed)
uv run autogenerateagentsmd .. --style comprehensive

This creates an AGENTS.md that teaches Copilot about the codebase structure, making vibe-coding suggestions much more accurate.

Step 5 — Pull a better LLM model into Ollama

The default model (phi) is small and fast. For better reasoning, pull a larger model when you have RAM headroom:

# Inside your Codespace terminal:
docker exec ollama ollama pull llama3.2        # ~4GB, good general model
docker exec ollama ollama pull mistral         # ~4GB, good for coding
docker exec ollama ollama pull deepseek-r1:7b  # ~5GB, strong reasoning

# List what's available
docker exec ollama ollama list

Update llm.config.json → providers.ollama.default_model to switch.

Step 6 — Set up n8n → Webhook notifications (optional)

Connect GitLab or GitHub pipeline events to n8n for custom notifications:

  1. In n8n: New workflow → Webhook trigger → copy the URL
  2. GitHub: Repo Settings → Webhooks → paste URL, select "Workflow runs"
  3. Or GitLab: Settings → Webhooks → paste URL, select "Pipeline events"
  4. Build a workflow that sends a Discord/Slack message or logs the result

🗺️ Reference repos worth exploring

These repos inspired the patterns in this starter kit and are worth exploring for ideas and code reuse:

RepoWhat it's useful for
ag2Multi-agent framework — good patterns for agent orchestration and pre-commit hooks
modme-ui-01Codespaces secrets management, MCP server integration patterns
Github-runner-packageAdvanced GitHub Actions: build matrix, npm/docker upgrade automation, stale bot
awesome-agent-skillsAgentSkills format, skill validation patterns
self-hosted-ai-starter-kitThe upstream project this is based on
foam-knowledgebaseFoam-based knowledge graph — good for documenting what you build
llama-fsLLM-powered file system organiser
open-multi-agentMulti-agent coordination patterns
agnoLightweight agent framework

⚠️ What still needs manual setup (things agents can't do for you yet)

TaskWhy it needs youHow to do it
Generate real API keysKeys are account-specific secretsVisit provider dashboards (OpenAI, Anthropic, etc.) and paste into .env or Codespaces Secrets
First-time n8n loginn8n requires interactive account creationOpen http://localhost:5678 and complete the form
GitLab account + importRequires account creation and OAuthFollow GITLAB_SETUP.md steps 1-3
Choosing an Ollama modelDepends on your RAM and use caseRun docker exec ollama ollama pull <model>
Foam knowledge basePersonal knowledge — agents can't write your notesClone foam-knowledgebase and start adding .md files
GitHub Codespaces billingFree tier has 60hr/month limitMonitor usage at github.com/settings/billing