Iqonga – AI Agent Framework – Open-Soruce

Posted on by — No Comments ↓

We’re Open-Sourcing Iqonga: An Agentic Framework You Can Run and Extend Today

Build multi-agent workflows, connect channels, and ship your own AI-powered product—with a stack that’s ready for Cursor and Claude.

Today we’re releasing the MVP of Iqonga as open source. Iqonga is an agentic framework for building solutions on AI agents: create agents, define multi-step workflows, connect channels (Telegram, Email AI, and more), and extend the platform to fit your use case. The entire backend and frontend are in one repo—no lock-in, no credits in the core—so you can fork, run, and build on it.

In this post I’ll cover what’s in the box, why we open-sourced it, and how Cursor and Claude AI make adoption and extension straightforward.

What is Iqonga?

Iqonga is a full-stack, open-source framework** for AI agents and workflows:

  • AI Agents – Create agents with configurable personalities and optional company knowledge. Use them in workflows or expose them via channels.

  • Multi-step workflows – Define flows with agent steps, human approval steps, conditional branching, and sub-workflows. Trigger manually, on a schedule, or via webhooks.

  • Channels – Connect Telegram bots, Email AI (Smart Inbox), and other channels so agents can interact with users where they already are.

  • Magic-code auth – Email-based login with one-time codes; no passwords to manage. Works with your own SMTP or returns the code in the API when SMTP isn’t configured.

  • Scheduled content – Schedule posts and content; optional job processor for delivery.

The stack is Node.js (backend) + React (frontend) with a PostgreSQL database. You get a single codebase: backend API, frontend UI, docs site (Docusaurus), and a simple info site—all in one repo so you can deploy and customize everything.

Why open source the MVP?

We want developers to run, experiment, and extend Iqonga without barriers. The MVP is the same codebase we use and deploy: agents, workflows, channels, auth, and UI. By open-sourcing it under GPL-3.0, we’re making it possible to:

  • Fork and host your own instance.
  • Add new agents, workflows, or channels.
  • Integrate with your existing tools and infra.
  • Learn from and contribute back to the project.

No payment or credits system in the core—just the framework and your ideas.

Ease of adoption with Cursor and Claude AI

A big focus for this release is low-friction adoption. The repo is structured so that Cursor and Claude AI can help you get running and iterate quickly.

Cursor

-Fork → Open in Cursor – Clone the repo and open the folder in Cursor. The AI has full context of the codebase: backend routes, frontend components, and config.

  • Explain and navigate – Ask Cursor to explain how magic-code auth works, where workflows are defined, or how to add a new API endpoint. It can point you to the right files and suggest changes.

  • Extend without guesswork – Describe what you want (“add an endpoint that returns workflow count”, “add a new step type”) and get targeted edits in the right places.

  • One place for backend + frontend – Node and React live in the same repo, so Cursor can refactor across the stack and keep naming and behavior consistent.

We’ve added a Build with Cursor guide in the repo that walks from fork → clone → env setup → run → extend. It’s the path we recommend for anyone building a solution on top of Iqonga.

Claude AI

  • Docs and setup – Use Claude to interpret the README, .env.example files, and migration docs. You can paste error messages or logs and get step-by-step fixes.

  • Architecture and design – Ask Claude to summarize how agents, workflows, and channels fit together, or to suggest where to add a new integration.

  • Copy-paste workflow – Share snippets of your .env, migration commands, or API examples; Claude can turn them into a minimal runbook for your team or a blog post.

Together, Cursor and Claude make it practical to go from “I forked Iqonga” to “I have a running instance and a new feature” without deep-diving the whole codebase first.

Get started in a few minutes

You need Node.js 20+, PostgreSQL, and (optionally) Redis. Then:

  1. Clone and open in Cursor (or your IDE) 
git clone https://github.com/zenthryx/iqonga.git
cd iqonga
  1. Backend 
cd backend
cp .env.example .env
Edit .env: set DATABASE_URL, JWT_SECRET, and optionally SMTP for magic-code email
npm install && npm run dev

Backend runs on port 3001.

  1. Frontend (new terminal) 
cd frontend
cp .env.example .env
Set VITE_API_URL=http://localhost:3001/api
npm install && npm run dev

Open http://localhost:5173, request a magic code (or use the code returned in the API if SMTP isn’t set), and you’re in.

Database: Run the migrations in docs/standalone_db/` (see the docs for full setup).

What’s next?

  • Try it – Fork the repo, open it in Cursor, and get the stack running locally.

  • Read the docs – In-repo guides: Build with Cursor, deployment troubleshooting, and the docs site for intro, workflows, and deployment.

  • Extend it – Add an agent, a workflow step, or a channel. Use Cursor or Claude to navigate and edit; the codebase is one full-stack app, so refactors can span backend and frontend.

  • Share feedback – Open issues or discussions on GitHub, or reach out via Zenthryx AI Lab · Twitter/X · Telegram.

Iqonga is a product of Zenthryx AI Lab. We’re excited to see what you build with it.

Links

Leave a Reply