CLI to scaffold and ship full-stack AI agent projects (FastAPI + React/Vite/TS)

Description

synapseForge is a PyPI package that provides a CLI to scaffold full-stack AI agent projects from scratch — backend (FastAPI), frontend (React/Vite/TypeScript), branding (logo, .ico, color palette), dependencies, and a self-contained distribution build.

The generated project includes:

• Agent Framework: AgentLoop with native tool calling, tools registry (native + external + MCP), sessions (SQLite WAL), per-agent permissions, skills and sub-agent delegation
• Multi-provider LLM: LOCAL (Ollama), Groq, Google Gemini and Gemini Embedding 2 — cloud API keys managed from the config panel, validated against each provider's API and stored encrypted in SQLite
• RAG knowledge base: ChromaDB vector collections with Gemini Embedding 2; upload files and web pages, cosine-similarity search
• LLM-assisted creation: standalone interfaces to generate skills, tools and agents through an iterative interview (with real tools enabled), with ephemeral cloud model selection per task
• Scheduled tasks: user-defined tasks (name + description + time + weekdays) managed from the header Agenda or via Telegram; each task can be equipped with tools, skills and model parameters, and its prompt refined with the LLM wizard. Activating a task creates a dedicated sub-agent with those permissions; the backend runs it on schedule and notifies the result in the UI bell and on Telegram
• Telegram bot: remote control that bridges messages to the agent through the web UI (commands, voice transcription, attachments)
• Frontend: chat with SSE streaming, config panel, sessions sidebar, context-window gauge, metrics dashboard
• Docker support and desktop app mode (heartbeat watchdog + shutdown endpoint)

Installation

pip install synapseForge

Package dependencies: Pillow (.ico generation) — everything else is project-level.

Requirements

LLM provider (required): at least one cloud API key is needed to use the app — OpenRouter, Google Gemini or Groq all offer free tiers. Keys are loaded from the in-app config panel (Providers) on first launch; nothing else has to be installed.

The knowledge base feature specifically requires an OpenRouter key (free tier works). Without it, that section stays disabled — everything else runs normally.

Ollama (optional): local models are supported but not required. Install Ollama only if you want to run models locally.

Quick Start

Create a new project

synapseforge init my-project
cd my-project

Interactive GUI pipeline (project data, logos, colors).

Run in development

synapseforge run ./my-project

Requires the project venv to be activated (VIRTUAL_ENV). Starts backend + frontend dev servers and opens the browser. Ctrl+C stops both.

Build a distributable

synapseforge launch -p ./my-project -n "MyApp"

Builds the frontend, bundles embedded Python and packages everything into a self-contained desktop app / zip ready to deliver. By default the backend ships as .py sources; pass -c / --compile to compile it to .pyc. Other options: --skip-frontend, --no-embed.

Alternatively, deploy the project as a container with the bundled Docker setup (docker compose up --build -d), which serves the built frontend from the backend in a single image.

Update to latest template

synapseforge update ./my-project

Backs up the entire project (including agent.db and config/replace.json), downloads the latest template, and restores your data. If anything fails, the project is automatically restored from the backup.

Update to latest template

synapseforge update ./my-project

Backs up the entire project (including agent.db and config/replace.json), downloads the latest template, and restores your data. If anything fails, the project is automatically restored from the backup.

Edit colors at runtime (no rebuild)

synapseforge colors ./my-project

GUI editor for frontend/public/colors.json. Refresh the browser (F5) to see changes instantly.

CLI Reference

Tech Stack

Support this project

synapseForge will always be free and open source. If you find it useful, consider supporting its development with a donation via Mercado Pago — your donation goes directly into new features, fixes and better docs for everyone.

License

Apache 2.0

Copyright (c) 2026 SYNAPSE AI SAS