Vibe Stack
Your autonomous software engineering team. One command to deploy.
Five senior engineers powered by Claude Opus, each paired with a DeerFlow research assistant running on local GPU inference. Paperclip handles orchestration -- scheduling, retries, multi-agent coordination, and human-in-the-loop review.
You (CEO)
|
CTO --- cto-assistant
/ | \ \
Backend Frontend QA DevOps
| | | |
backend- frontend- qa- devops-
assistant assistant asst. assistant
-- Claude Opus (API) -- -- Qwen 3.5 9B (local vLLM) --
5 senior engineers 5 research assistants
You create an issue. The CTO decomposes it, dispatches research to free local-GPU assistants, then delegates implementation to Opus-powered engineers. Each engineer wakes with research context already gathered, executes, and posts results. The CTO reviews, requests fixes if needed, and pushes the feature branch.
- Zero-config setup -- one command installs, configures, and bootstraps the full 10-agent org
- Stateless agents -- all state lives in the Paperclip issue tree; killed containers retry with zero data loss
- Cost-optimized -- Opus for deep reasoning, free local vLLM for research; engineers are rate-limited to 1-2 web lookups and must delegate broad research
- Self-improving -- agents detect recurring quality issues and propose source code changes to themselves, gated by a 5-stage safety pipeline with human review
- Cross-run learning -- each heartbeat persists spec, output, and critic feedback to a per-agent memory store with importance + 30-day decay; future runs recall scoped context via BM25 + semantic hybrid
- Role-based tool filtering -- each agent only sees tools relevant to their role
- 3400+ tests across 91 files covering all major subsystems
| Requirement | Notes |
|---|---|
| Linux | Ubuntu/Debian, Fedora/RHEL/CentOS, Arch/Manjaro, or openSUSE |
| Docker Engine 24+ | With Compose v2 |
| Tailscale | Install and run tailscale up |
| NVIDIA GPU (optional) | 8GB+ VRAM with nvidia-container-toolkit for local inference |
git clone https://github.com/tmartin2113/Vibe-Stack.git
cd Vibe-Stack
sudo ./setup.shSetup auto-detects your hardware, generates secrets, clones skill sources, builds service images, bootstraps the 10-agent org, and applies security hardening. Progress is displayed as [Step N/24].
| Hardware | What You Get |
|---|---|
| NVIDIA GPU (8GB+ VRAM) | Claude Opus engineers + local vLLM assistants + full infrastructure |
| No GPU | Claude Opus engineers only (cloud-only mode) |
After setup completes, open the Paperclip UI at the URL printed by setup to create your admin account.
# Full stack (default with GPU)
docker compose up -d
# Core + infrastructure (no GPU services)
docker compose -f docker-compose.yml -f docker-compose.infra.yml up -d
# Core only (minimal)
docker compose -f docker-compose.yml up -dLocal Development
Build the Paperclip server and DeerFlow from local source instead of GHCR images:
cp docker-compose.override.yml.example docker-compose.override.yml
# Set PAPERCLIP_SOURCE_DIR in .env to your local paperclip checkout
docker compose up -d --build1. You create an issue in the Paperclip UI
2. CTO wakes -> creates feature branch -> writes ARCHITECTURE.md -> creates subtask pairs
3. Assistants wake -> run pre-flight research (unrestricted web search) -> post findings
4. Engineers wake with context -> implement (rate-limited to 1-2 web lookups) -> post results
5. CTO wakes -> reviews all work -> creates fix subtasks if needed -> pushes feature branch
| Senior Engineers (Claude Opus) | ||
|---|---|---|
| CTO | Architect & reviewer | Task decomposition, code review, branch management |
| Sr. Backend | Server-side | APIs, databases, auth, integrations |
| Sr. Frontend | Client-side | UI components, styling, UX, browser logic |
| Sr. QA | Quality & security | Test plans, security audits, coverage analysis |
| Sr. DevOps | Infrastructure | Docker, CI/CD, deployment, monitoring |
| Research Assistants (local vLLM -- zero API cost) | ||
|---|---|---|
cto-assistant | CTO | Architecture research, codebase exploration |
backend-assistant | Sr. Backend | API docs, library examples, best practices |
frontend-assistant | Sr. Frontend | Component libraries, CSS patterns, framework docs |
qa-assistant | Sr. QA | Testing strategies, security checklists, coverage tools |
devops-assistant | Sr. DevOps | Docker best practices, CI/CD patterns, infra docs |
Agents detect recurring quality issues and propose improvements to their own source code:
Signal accumulation -> Threshold (3+ signals) -> 5-gate safety pipeline -> Human review
|
|-- Path validation (agents/ only)
|-- Diff size (<500 lines)
|-- Full pytest suite
|-- Bandit security scan
|-- Critic scoring (>=90)
Proposals appear in the Paperclip Improvements section with branch name and review instructions.
Each agent runs a deterministic state machine with built-in task types:
Router -> Skill Loader -> Spec Builder -> Specialist -> Critic -+
^ |
| score < 85 |
+-------------------+
- Hybrid routing -- regex + semantic matching selects the right specialist adapter
- Critic-driven refinement -- iterative quality improvement (threshold: 85/100)
- Task decomposition -- complex requests split into parallel specialist subtasks
- 5000+ skills -- auto-loaded per task type from 5 curated sources
- Docker sandboxing -- OpenSandbox with GPU passthrough
| Backend | Type | Auth |
|---|---|---|
| vLLM (default) | Local GPU inference | None |
| OpenAI | Cloud API | OPENAI_API_KEY |
| Anthropic | Cloud API | ANTHROPIC_API_KEY |
Multi-backend failover with per-backend circuit breakers via BackendPool. Transparent to the agent layer.
Core (docker-compose.yml -- always running):
| Service | Purpose | Port |
|---|---|---|
| Paperclip | Control plane + UI | 3100 |
| DeerFlow LangGraph | Research assistant backend | 2024 |
| DeerFlow Gateway | Research assistant API | 8001 |
| Vibe | Agent orchestrator | 8080 |
| Tailscale | Mesh VPN + HTTPS | -- |
Infrastructure (docker-compose.infra.yml):
| Service | Purpose | Port |
|---|---|---|
| SearXNG | Self-hosted web search | 8888 |
| Gitea | Git hosting | 3000 |
| MinIO | S3-compatible object storage | 9000 |
| Playwright | Browser automation | 3003 |
| Penpot | Design tool | 9001 |
| MiroFish | Multi-agent simulation | 5001 |
| PaddleOCR | OCR text/layout extraction | 8868 |
| Dev Runner | Sandboxed code execution | 8585 |
| SSH Relay | Git SSH relay | -- |
| Prometheus | Metrics collection | 9091 |
| Grafana | Monitoring dashboards | 3333 |
| Zep + Neo4j | Agent memory graph | 8394 |
GPU (docker-compose.gpu.yml):
| Service | Purpose | Port |
|---|---|---|
| vLLM | Local model inference | 8000 |
| OpenSandbox | Code execution sandbox | 9090 |
| ComfyUI | Image generation | 8188 |
Tailscale provides HTTPS access; there is no separate reverse proxy container (Caddy runs as a host systemd service if installed by setup.sh).
For detailed subsystem documentation, see docs/architecture.md.
See .env.example for all configurable values. Key variables:
| Variable | Purpose | Default |
|---|---|---|
VLLM_MODEL |
Local inference model | Auto-detected by GPU VRAM |
GH_TOKEN |
GitHub PAT for agent git push | -- |
VIBE_SANDBOX_BACKEND |
opensandbox or subprocess |
subprocess |
VIBE_STORAGE_BACKEND |
sqlite or postgres |
sqlite |
VIBE_CACHE_BACKEND |
memory or redis |
memory |
LOG_LEVEL |
Logging verbosity | WARNING |
Infrastructure service URLs (SEARXNG_URL, MIROFISH_URL, PADDLEOCR_URL, etc.) are auto-configured by setup.sh. See docs/architecture.md for the full configuration reference.
The Paperclip server container (vibe-stack-server-1) loads its adapter skills from $PAPERCLIP_SKILLS_DIR, which the published server image sets to /app/skills. You can override it via docker-compose.yml to bind-mount a host directory for runtime skill swapping — e.g. to drop customized SKILL.md files into a volume that outlives container rebuilds.
Two operator helpers live in scripts/:
| Script | Purpose |
|---|---|
scripts/check-paperclip-skills.sh |
Verify the active skill dir, list loaded skills, and warn about stale npx caches. Safe to run anytime. |
scripts/cleanup-paperclip-skill-cache.sh |
Purge stale /paperclip/.npm/_npx/* caches left by earlier Paperclip setup steps. Dry-run by default; pass --apply to delete. |
Typical first-time cleanup:
./scripts/check-paperclip-skills.sh # inspect current state
./scripts/cleanup-paperclip-skill-cache.sh --apply # purge ~hundreds of MB of stale cache
./scripts/check-paperclip-skills.sh # confirm the warning clearsBoth scripts honor SERVER_CONTAINER=<name> if your container is named differently.
# Full suite (~3400 tests across 91 files)
python -m pytest tests/ -x -m "not e2e" --no-header -qRun specific subsystems
python -m pytest tests/test_heartbeat.py -v # Heartbeat lifecycle (149 tests)
python -m pytest tests/test_skill_security.py -v # Security hardening (152 tests)
python -m pytest tests/test_tool_system.py -v # Tool system (157 tests)
python -m pytest tests/test_mirofish_tool.py -v # MiroFish simulation (11 tests)
python -m pytest tests/test_ocr_tool.py -v # OCR tool (21 tests)
python -m pytest tests/test_memory_store.py -v # Long-term memory (167 tests)
python -m pytest tests/test_message_store.py -v # Message bus (73 tests)| Component | Minimum | Recommended |
|---|---|---|
| RAM | 16 GB | 32 GB+ |
| GPU VRAM | 8 GB (4B model) | 22 GB+ (9B model) |
| CPU | 4 cores | 16 cores |
| Disk | 50 GB | 100 GB+ |
| OS | Any systemd-based Linux | Ubuntu 24.04, Fedora 41+ |
No GPU required for cloud-only mode (Claude/OpenAI backends).
# Health check
python -m agents.main --doctor
# Service status
docker compose ps
# Agent logs
docker compose logs --tail 30 vibe
# DeerFlow assistant logs
docker compose logs --tail 30 deerflow-langgraph deerflow-gateway
# Re-run setup (idempotent)
sudo ./setup.shSee CONTRIBUTING.md for guidelines.
MIT License. See LICENSE for details.
Paperclip | DeerFlow | Qwen | MiroFish | PaddleOCR | Impeccable | OpenSandbox | Anthropic Skills | Obra Superpowers | Vercel Agent Skills | VoltAgent OpenClaw