⬢ DevFoundry

Documentation

Everything to go from install to a deployed app. The full reference lives in the repo: Features · Tutorial · Architecture · Troubleshooting · Roadmap

1. Get started 2. Desktop · CLI · Web 3. Models & reasoning 4. Deep Research 5. Free deploys 6. About Docker 7. Troubleshooting

1. Get started (60 seconds)

No Docker. No API keys required. The orchestrator runs inside the app and auto-detects local model runtimes (Ollama, LM Studio, FreeLLMAPI). Docker and cloud keys are optional extras.

Install — grab the latest release (.dmg macOS · .msi/.exe Windows · .deb/.rpm/.AppImage Linux) and open it. The orchestrator starts automatically — the header dots turn green.
Give it a brain — either run a local model (ollama pull qwen2.5-coder:14b — the Models page recommends the best fit for your RAM/chip) or paste any provider key and click Use. Verify with ⚡ Test LLM.
Forge — pick a Skill (e.g. Premium landing page), a Reasoning mode, type your idea, hit Forge It. Watch Spec → Design → Codebase → Refine → Deploy stream live.
Inspect — the Code tab is a real editor; Canvas previews the app (it can run the actual dev server); History keeps every run.

2. Three surfaces: desktop, CLI, web

Surface	How	Best for
Desktop app	Install from Releases	The full experience: native menus, tray, ⌘⇧A, notifications, Keychain, auto-update
CLI	`pip install -e backend` → `devfoundry`	Scripting & CI: `devfoundry forge "idea" --skill premium-landing --reasoning deep`
Web app	`devfoundry serve` → localhost:9100/app	The same UI in any browser — headless machines, remote boxes

# CLI quick tour
devfoundry serve                 # orchestrator + web app
devfoundry forge "a kanban board with drag and drop" --skill web-app-crud
devfoundry research "state of on-device LLMs" --out report.md
devfoundry runs                  # history
devfoundry version               # version & credits

3. Models & reasoning

24 providers — cloud (Anthropic, OpenAI, Groq, Google, Mistral, …), keyless (OpenCode Zen), self-hosted (FreeLLMAPI), and fully local (Ollama, LM Studio). Keys are pasted once on the Models page, stored on your machine (optionally in the OS Keychain), and read live.

Auto-detect — with nothing configured, the first running local runtime is used.
MoE stage experts — a different model per stage (e.g. a coder model for codegen).
Rotation — automatic failover across providers on rate limits/errors; one click builds a rotation from every free provider you have.
Reasoning modes — ⚡ Fast (single-shot) · ⚖ Balanced (ToT design) · 🧠 Deep (Self-MoA codegen) · 🎭 Ensemble (MoA across distinct providers) · 🧭 Auto (complexity-routed). Each label states its cost multiple.
Your machine — the app reads your RAM/chip/GPU and recommends local models that actually fit.

4. Deep Research

Multi-step web research with a live step log: plan sub-queries → search → read sources → cited markdown report (copy or download). Works keyless out of the box; add a free Brave or Tavily key in Settings → Research for full web search.

5. Free deploys

Target	Cost	Notes
Netlify	free	static hosting, custom domain supported
Vercel	free hobby	via token
Cloudflare Pages	free	via API token + account id
Surge.sh	free	custom domain supported
Hugging Face Spaces	free CPU	gradio/static auto-detected
Local	free	Docker image (if a Dockerfile exists) or a zip bundle — always works

6. About Docker — optional, never required

DevFoundry does not need Docker. The default embedded mode runs the whole pipeline inside the app, and the companion services run as native processes DevFoundry manages itself: the Qdrant vector store (one-click native binary) and the FreeLLMAPI gateway (built once into the workspace, then supervised as a plain Node process — Services → "Embed"). The code sandbox is OS-native too (sandbox-exec/bwrap). Docker remains an optional "isolated mode" for containerized engines and container deploy builds; without it everything degrades gracefully and works identically.

7. Troubleshooting (quick)

Symptom	Fix
"No LLM provider configured"	Models page → paste a key + Use, or start Ollama/LM Studio (auto-detected). Confirm with ⚡ Test LLM.
Header dots stay red	The orchestrator auto-starts; give it ~10s. Else click Start services, or check `/tmp/devfoundry-autostart.log`.
"Tests skipped — not a code failure"	Normal: the generated test env can't run; it's reported honestly instead of looping.
Cloud deploy fails	Missing token — it falls back to a zip and names the token to add in Settings → Deployment.
Gatekeeper/SmartScreen warning	Builds are not yet notarized (roadmap). Right-click → Open on macOS.

More: full troubleshooting guide.

⬢ DevFoundry — MIT. Created by King3Djbl of KingLabs (HF · Ollama), built with Claude Code.