---

---

 

---

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 (description + time + weekdays) managed from the header Agenda or via Telegram; the backend runs them with the selected model 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

Tool	Version	Needed for
Python	3.12+	init, launch, run, colors
Node.js	20+	launch (frontend build), run (dev server)
Docker	20+	Optional: containerized deployment

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

Command	Description
synapseforge init [dir]	Scaffold a project from bundled template (GUI)
synapseforge launch -p <path> -n <exe> [--skip-frontend] [--no-embed] [-c]	Build self-contained desktop app / distribution zip (-c compiles backend to .pyc, default ships .py)
synapseforge colors [dir]	Edit frontend/public/colors.json via GUI (live reload)
synapseforge run [dir]	Start uvicorn + npm dev servers, open browser (venv must be active)
synapseforge update [dir]	Update project to latest template (preserves agent.db, config, colors)
synapseforge --help	Show global help

---

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

---