The Code → Download ZIP button at the top of this page gives you the source code, not the app. To install AgentSuiteLocal:
▶ Download the installer from the Releases page
- Windows:
AgentSuiteLocal-1.0.0-setup.exe- macOS:
AgentSuiteLocal-v1.0.0.dmg
v1.0.0 — Desktop UI for AgentSuite, running 100% local via Ollama. Built for non-technical founders — no CLI, no API key, no cloud required.
Seven specialist agents (Founder, Design, Product, Engineering, Marketing, Trust/Risk, CIO) walk a five-stage pipeline and write a structured artifact library to your disk. You review, approve, and promote outputs into a persistent kernel that feeds every future run. All seven agents are enabled by default; override via AGENTSUITE_ENABLED_AGENTS.
What's included in v1.0.0: all seven agents enabled by default, five-stage pipeline with live SSE progress, approval gate with QA scores across nine dimensions, kernel versioning, model management with pull progress, multi-agent pipelines, project management, run export (ZIP/Markdown/PDF), cloud model fallback (Claude via Anthropic API), desktop notifications, auto-update check, OS keychain for API key storage, and crash recovery. See CHANGELOG.md for the full history.
Distributable users (download from Releases — no Python or Node needed):
| Minimum | Recommended | |
|---|---|---|
| OS | Windows 10 64-bit | Windows 11 |
| RAM | 8 GB (Light tier) | 16 GB (Balanced) |
| Disk | 10 GB free | 20 GB free |
| Ollama | any | latest |
Developers (building from source):
| Minimum | |
|---|---|
| Python | 3.11 |
| Node.js | 20 |
Supported models: gemma4:e2b (8 GB), gemma4:e4b (16 GB, recommended), gemma4:26b (32 GB).
Runs entirely on-device — no internet connection required after setup.
Non-technical users: download AgentSuiteLocal-1.0.0-setup.exe from the Releases page and run it. The Inno Setup installer handles installation to Program Files and optionally adds a desktop shortcut. The in-app installer then handles Ollama, model download, and smoke test — no terminal required.
Developers: see Development mode below.
AgentSuiteLocal is free, open-source beta software and the Windows build is not code-signed yet. Because of that, Windows may show the scary SmartScreen popup ("Windows protected your PC") the first time you run the installer. This is expected for unsigned OSS beta builds downloaded from GitHub Releases.
Only continue if you downloaded the installer from the official AgentSuiteLocal Releases page. To proceed:
- Click More info (below the warning text).
- Click Run anyway.
You will usually only see this once per machine. If you prefer to verify the binary before running, check the SHA-256 hash in the release notes against the file you downloaded:
Get-FileHash .\AgentSuiteLocal.exe -Algorithm SHA256Because the DMG is unsigned, macOS may show "AgentSuiteLocal cannot be opened because it is from an unidentified developer." To open it:
- In Finder, right-click (or Control-click) the app icon inside the mounted DMG.
- Choose Open from the context menu.
- Click Open in the warning dialog.
You will only need to do this once. If the app is already blocked (quarantine flag set), go to System Settings → Privacy & Security → scroll down to the blocked app entry → click Open Anyway.
# Requires Python ≥ 3.11, Node.js ≥ 18, pyinstaller, and (Windows) Inno Setup 6
pip install -e ".[dev]" pyinstaller
make dist # auto-detects OS — builds frontend then runs PyInstaller
# or explicitly:
make build-mac # → dist/AgentSuiteLocal.app (macOS)
make build-win # → dist/AgentSuiteLocal/ (Windows onedir)
make build-installer # → dist/AgentSuiteLocal-1.0.0-setup.exe (Windows only, requires Inno Setup)The onedir output is self-contained — no Python or Node required on the target machine. build-installer wraps the onedir into a standard Windows installer with uninstall support.
For iterating on the source, run two terminals:
# Terminal 1 — backend (auto-reload on save)
uvicorn agentsuitelocal.api.main:app --reload --port 8766
# Terminal 2 — frontend with HMR
cd web && npm run devVite proxies /api/* to :8766. Open http://localhost:5173 (or whichever port Vite prints).
agentsuitelocal/
api/
main.py FastAPI app entrypoint — wires routers + middleware
config.py Settings load/save, OS keychain (post-v0.7.1), tier→model map
execution.py Run/pipeline orchestration, _resolve_llm, SSE state
routers/ Split per concern (post-v0.8.0): health, kernel, ollama,
pipelines, projects, runs, settings, system, uninstall
schemas.py Pydantic request/response models
workspace.py Filesystem layout for runs + kernel artifacts
web/
src/
App.jsx Router + scene switching
data.js Static agent/model/stage definitions
hooks/
useSSE.js SSE → React state bridge
components/
installer/ 6-screen setup wizard (Welcome → License → HardwareTier → OllamaModel → Smoke → Success)
InstallerShell.jsx Chrome (header, nav, progress)
ScreenWelcome.jsx Step 1 — splash
ScreenLicense.jsx Step 2 — license gate
ScreenHardwareTier.jsx Step 3 — hardware probe + tier selection
ScreenOllamaModel.jsx Step 4 — Ollama runtime + model download
ScreenSmoke.jsx Step 5 — first-run smoke test
ScreenSuccess.jsx Step 6 — launch
(legacy/unused: ScreenHardware, ScreenTier, ScreenOllama,
ScreenModelDownload, ScreenPython, ScreenAgents, ScreenApiKey,
ScreenUninstall — kept for direct reference)
app/ 12 main app screens
Dashboard.jsx Overview + pending approvals
AgentsView.jsx Agent roster
NewRunView.jsx Goal input + launch (B6 path validation)
LiveRunView.jsx SSE-driven pipeline progress (B1/B3/B4/E2)
ApprovalGateView.jsx Artifact review + QA scores (C1/C2/C3/D1/D4)
KernelView.jsx Approved artifact library (H4)
ModelView.jsx Ollama model management + pull (G3)
PipelineView.jsx Multi-agent chain builder
ProjectsView.jsx Project cards (rename/archive/delete) (H5)
RunsView.jsx Full run history + inline detail (H3/B5/E1)
SettingsView.jsx Model, behavior, cloud, workspace (G1/G2/B3/C1)
ManualView.jsx In-app user guide
CrashBanner.jsx Crash report banner (F4)
shell/
index.jsx Sidebar, TopBar, TrayMenu
ui/
index.jsx Icon, MetricCard, ProgressBar, Toggle
Data flow: POST /api/run starts a background task that invokes the selected AgentSuite agent directly via BaseAgent.run(). The frontend subscribes to GET /api/run/{id}/stream (SSE) and renders progress in real time. When the agent finishes, the run enters waiting state and the approval gate becomes available. Approving promotes artifacts to ~/AgentSuite/.agentsuite/_kernel/{project}/{agent}/.
See docs/architecture.md for the full design doc.
| Method | Path | Description |
|---|---|---|
| GET | /api/health |
Ollama daemon + model status |
| GET | /api/hardware |
CPU, RAM, disk probe |
| GET | /api/ollama/status |
Detailed Ollama status |
| POST | /api/run |
Start a run, returns run_id |
| GET | /api/run/{id}/stream |
SSE — live pipeline events |
| GET | /api/run/{id} |
Run status + artifacts + QA score |
| POST | /api/run/{id}/approve |
Promote artifacts to kernel |
| POST | /api/run/{id}/reject |
Reject without promoting |
| GET | /api/runs |
All runs, newest first |
| GET | /api/kernel |
All kernel artifacts by project |
| GET | /api/projects |
Project list derived from runs |
| POST | /api/pipelines |
Create and start a multi-agent pipeline |
| GET | /api/pipelines |
All pipelines, newest first |
| GET | /api/pipelines/{id} |
Pipeline status + step results |
| GET | /api/pipelines/{id}/stream |
SSE — live pipeline step events |
| POST | /api/pipelines/{id}/approve |
Approve current step, advance to next |
| POST | /api/pipelines/{id}/reject |
Reject current step, halt pipeline |
| GET | /api/settings |
Current settings — API key redacted |
| POST | /api/settings |
Replace settings (full object) |
| PATCH | /api/settings |
Partial update |
| POST | /api/run/{id}/cancel |
Cancel a running run; saves partial artifacts |
| GET | /api/run/{id}/export/{format} |
Export run as zip, markdown, or pdf |
| POST | /api/open-folder |
Open export folder in Explorer/Finder |
| GET | /api/kernel/diff |
Unified diff between two kernel files |
| POST | /api/validate-path |
Validate an inputs_dir path |
| GET | /api/ollama/models |
List installed Ollama models |
| POST | /api/ollama/pull |
Pull a model (SSE progress stream) |
| DELETE | /api/ollama/models/{name} |
Delete an installed model |
| GET | /api/model/verify/{name} |
Verify model is functional |
| GET | /api/update/check |
Check for a newer GitHub release |
| GET | /api/version |
Return current version, e.g. {"version": "1.0.0"} |
| GET | /api/crash-reports/latest |
Most recent crash report |
| GET | /api/telemetry/summary |
Local usage event counts |
| GET | /api/launcher/port |
Port read from ~/.agentsuitelocal/launcher.port.json |
| POST | /api/pipelines/{id}/resume |
Resume an errored pipeline step |
| GET | /api/projects |
All projects |
| POST | /api/projects/{slug}/rename |
Rename a project |
| POST | /api/projects/{slug}/archive |
Archive a project |
| DELETE | /api/projects/{slug} |
Delete a project and its runs |
| GET | /api/runtime/verify |
Bundle integrity check |
SSE event types: agent_start · stage_update · agent_done · agent_waiting · pipeline_step_done · pipeline_done · error · timeout · cancelled
pip install -e ".[dev]"
playwright install chromium
# Unit + integration (no browser, no Ollama required)
pytest tests/test_api.py tests/test_integration.py -v
# Live Ollama tests (requires Ollama running with a model loaded)
pytest tests/test_ollama_live.py -v -m ollama
# E2E browser tests (local dev):
# Vite dev server must be running on :5173 (npm run dev)
# Backend is auto-started on :8766 by conftest if not already up
pytest tests/e2e/ -v -m e2eCI runs Python unit + integration tests and Vitest frontend tests on every push (Ubuntu, Python 3.11 + 3.12 matrix). E2E runs in a separate job after a production build — the CI E2E job starts the backend on :8765 and sets BASE_URL=http://localhost:8765, testing against the built frontend served by FastAPI rather than the Vite dev server. See .github/workflows/ci.yml.
| Layer | Tech |
|---|---|
| Backend | FastAPI · uvicorn · sse-starlette · httpx · psutil |
| Frontend | React 18 · Vite · vanilla CSS |
| LLM runtime | Ollama (local, no cloud) |
| Agent engine | AgentSuite |
| Tests | pytest · pytest-playwright · Playwright (Chromium) |
| CI | GitHub Actions |
Runs and kernel artifacts are written to ~/AgentSuite/ by default. Override with AGENTSUITE_WORKSPACE=/your/path.
~/AgentSuite/
.agentsuite/
runs/
run-abc123/ one directory per run
brand-system.md
qa_scores.json
...
_kernel/
myco-pivot/
founder/ promoted artifacts feed future runs
brand-system.md
...
Some antivirus tools flag PyInstaller-bundled executables as suspicious. This is a known false positive with self-contained Python apps — the binary contains a Python interpreter, which some heuristic scanners misclassify.
Windows Security: Settings → Virus & threat protection → Manage settings → Add or remove exclusions → Add an exclusion for the AgentSuiteLocal install folder (default: C:\Program Files\AgentSuiteLocal).
VirusTotal: If you want to verify the binary independently, upload AgentSuiteLocal.exe to virustotal.com. A handful of low-reputation engine detections is normal for PyInstaller onedir bundles and does not indicate malware.
All data stays on your machine. No telemetry is sent to any server.
When the Usage telemetry toggle is enabled in Settings, AgentSuiteLocal writes a local log (~/.agentsuitelocal/usage.jsonl) that counts run starts, model used, and QA pass/fail scores. This file never leaves your machine. Disable the toggle to stop all logging.
Your cloud API key (if configured) is stored in the OS credential store — Windows Credential Manager on Windows, Keychain on macOS, Secret Service on Linux. It is never written to settings.json or any other file on disk.
See CHANGELOG.md for the full release history.
v1.0.0 (2026-05-08): First stable release. Sprint A–C v1.0 milestone: agentsuite repinned to v1.1.1 (closes V1+V2); real-LLM qa_score via QAReport.average field-name fix (V4); DI refactor for _save_state/_log_telemetry/_load_settings (9 INTERNAL-SUSPECT-REFACTOR sites closed); PipelineCard React key fix; a11y Bar 1 (Sidebar aria-current, modal Esc + role/aria-modal, Playwright runtime tests); bundle-launch smoke CI on macOS + Windows; one-run-per-session limitation declared. See release notes and CHANGELOG for full detail.
| Version | Highlights |
|---|---|
| v0.8.9 | 7 audit Criticals closed — Trust/Risk slug fix; broken gemma4:26b-moe → gemma4:26b; PDF-export HTML escape; SettingsView save-error UX; events-list cap; in-app ManualView refresh; test_execution.py restructure |
| v0.8.8 | Bug-fix release: missing ollama SDK in runtime deps + 3 audit rounds (28 Critical/Major fixes) + landing-page/seeds/manual refresh |
| v0.8.7 | Issue #19 — migrate pipeline execution to PipelineOrchestrator; K1 cross-stage context now active |
| v0.8.6 | Regression-guard tests for progress_callback; fix step key collision in pipeline SSE |
| v0.8.5 | AgentSuite v1.1.0 pin; wire intra-stage stage_update SSE events; close Issue #10 |
| v0.8.4 | Complete node24 migration — softprops/action-gh-release missed in Sprint 0 |
| v0.8.3 | Test floor for entry-point env-var; single version source of truth; README sync |
| v0.8.2 | Fix wheel metadata (was shipping as v0.7.1); dynamic pyproject.toml version |
| v0.8.1 | Enable all seven agents by default; enabled-agents env-var regression tests |
| v0.8.0 | Replace PipelineOrchestrator shim; direct BaseAgent.run() invocation |
| v0.7.1 | 30+ bug fixes; OS keychain; supply-chain hardening; Windows installer |
- PDF export uses reportlab (pure Python) and works out of the box on all platforms — no GTK or native runtime required.
- macOS DMG is unsigned. See the Gatekeeper guidance above. Apple Developer ID codesigning is on the roadmap.
- One run at a time per session. v1.0 supports a single active agent run (or pipeline step) per AgentSuiteLocal session. Starting a second run while one is in progress is not supported in the UI and is unsafe in the backend. Concurrent runs land in v1.1.
- E2E test suite requires a running Vite dev server (
:5173) or built frontend; the backend on:8766is auto-started bytests/e2e/conftest.py. The CI workflow (.github/workflows/ci.yml) pullsgemma4:e4bso the smoke-step model-installed check passes against_SETTINGS_DEFAULTS["model_name"]. Local E2E runs need the same model installed, or the smoke step fails on Step 5 of the installer walk.
MIT — see LICENSE.
The bundled Gemma 4 model carries Google's open-weight license.