Source-available under the Business Source License 1.1. Free for personal, educational, research, and non-production evaluation. Production or commercial use (internal tooling, hosted services, redistribution as a product) requires a separate commercial license — converts to Apache 2.0 on 2030-05-09. Commercial inquiries: balachander.ral@gmail.com.
Features • Quick Start • What's interesting • Architecture • Documentation
Oniva is an enterprise-grade platform for building, deploying, and managing AI agent workflows through a visual drag-and-drop interface. Think Zapier for AI agents — with crash-safe durable execution, cryptographic audit trails, and a state-machine-enforced safety layer that survives both LLM hallucinations and infrastructure failures.
▶ Watch the demo — visual workflow builder, durable execution, signed audit log, connectors.
Core value proposition:
- Visual workflow builder that non-engineers can drive end-to-end
- Durable execution via DBOS — workflows survive crashes, restarts, and 8+ hour sessions
- Tamper-proof audit trail — RSA-2048 signed, hash-chained, 7-year retention
- Tenant-isolated at the database level (PostgreSQL Row Level Security)
The Oniva codebase is more than a CRUD frontend over an LLM call. A few things worth a look if you're evaluating engineering depth:
- State machine + tool masking (
backend/app/agents/state_machine.py,stateful_agent.py) — agents are wrapped in a 7-state, 15-transition machine that masks unavailable tools at the logits layer, not just at validation time. Survives LLM attempts to call disallowed tools mid-thought. - DBOS-checkpointed durable workflows (
backend/app/services/durable_workflow_engine.py) — every workflow step persists transparently; crash mid-execution and the next worker resumes from the last checkpoint with no data loss. - Hash-chained, RSA-2048 signed audit log (
backend/app/services/audit_logger.py) — every decision the system makes is provably linked to the previous one. Designed for SEC / MiFID II / SOX-style replay. - OpenAPI-spec-driven connector factory (
backend/app/connectors/openapi/) — drop in any OpenAPI spec, get a fully sandboxed MCP-style tool with SSRF protection, private-IP blocking, and per-tenant credential resolution. - PostgreSQL RLS with transaction-scoped tenant context (
backend/app/database.py, migrations 011/043) —current_setting('app.current_tenant', true)::uuidgates every query;db.flush()+db.refresh()keeps the LOCAL setting alive across nested operations. - Three-tier memory — Redis hot cache → PostgreSQL warm → S3 cold for artifacts; pgvector HNSW indexes for semantic recall.
- 30+ node types — agents, logic, transforms, integrations
- React Flow canvas with real-time streaming execution
- Automatic checkpointing and crash recovery via DBOS
- Pre-built agents — Data Retrieval, Analysis, Compliance, Research
- Custom agents with personalized prompts and tool sets
- State-machine-enforced execution — invalid tool calls are masked, not just rejected
- Test/deploy gates with automated evaluation before production
- 4 native MCP connectors — ServiceNow, Microsoft Teams, OFAC, OpenAPI factory
- 31 OpenAPI-derived connectors — Stripe, Slack, GitHub, HubSpot, Jira, Notion, and more
- Custom imports — point at any OpenAPI spec, get a sandboxed tool
- Cryptographic audit trails with hash chaining
- 7-year artifact retention (S3-compatible)
- Workflow replay for regulator audits
- Human-in-the-loop approval queues for high-risk decisions
- Docker and Docker Compose
- Node.js 20+ and Python 3.12+ (for local development)
- An LLM provider key (OpenAI, Anthropic, or OpenRouter)
git clone https://github.com/supremeb/Oniva-ai.git
cd Oniva-ai
cp .env.example .env
# Edit .env: set OPENAI_API_KEY (or ANTHROPIC_API_KEY / OPENROUTER_API_KEY)
# and replace any CHANGE_ME_* placeholders.
docker compose updocker compose up -d postgres redis
# Backend (Terminal 1)
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000
# Frontend (Terminal 2)
cd frontend
npm install && npm run dev| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| API docs | http://localhost:8000/docs |
| PostgreSQL | localhost:5432 |
| Redis | localhost:6379 |
| Layer | Technologies |
|---|---|
| Frontend | Next.js 15, React, TypeScript, @xyflow/react 12, TanStack Query, Tailwind CSS, Radix UI |
| Backend | FastAPI 0.115, Pydantic AI, SQLAlchemy 2.0 async, DBOS, LiteLLM |
| Sandbox | E2B (per-tenant code-execution sandboxes) |
| Database | PostgreSQL 16 + pgvector, Redis 7 |
| LLM | OpenAI, Anthropic, OpenRouter (via LiteLLM) |
| Container | Docker, Docker Compose, Kubernetes |
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ Frontend │─────▶│ FastAPI │─────▶│ PostgreSQL │
│ (Next.js) │ │ Backend │ │ + pgvector │
└─────────────┘ └─────┬───────┘ └──────────────┘
│
▼
┌──────────────┐
│ LLM Providers│
└──────────────┘
Oniva-ai/
├── frontend/ # Next.js 15 app
│ ├── app/(dashboard)/ # Authenticated dashboard routes
│ ├── components/ # UI + workflow nodes
│ └── lib/ # API clients, Zustand stores
│
├── backend/ # FastAPI app
│ ├── app/
│ │ ├── api/v1/ # ~399 endpoints across 55 modules
│ │ ├── agents/ # Agent + state machine code
│ │ ├── connectors/ # MCP + OpenAPI connector factory
│ │ ├── services/ # Durable workflows, sessions, audit
│ │ └── models/ # SQLAlchemy 2.0 models
│ └── migrations/ # Alembic schema migrations
│
└── docker-compose.yml # Local development
Architecture features are env-controlled. See backend/app/config/__init__.py for the source of truth.
USE_DURABLE_WORKFLOWS = True # DBOS checkpointing
USE_FILESYSTEM_SESSIONS = True # Plan / todo recitation
USE_VOLUMES = True # Pre-warmed input data
USE_ARTIFACTS = True # 7-year compliance storage
USE_STATE_MACHINE = True # Tool masking
USE_EPISODIC_MEMORY = True
USE_USER_PREFERENCES = TrueThe backend exposes ~399 REST endpoints across 55 modules. A few highlights:
| Endpoint | Description |
|---|---|
GET /health |
Health check |
CRUD /api/v1/agents |
Agent management |
CRUD /api/v1/workflows |
Workflow management |
POST /api/v1/workflows/execute-durable |
DBOS-checkpointed execution |
POST /api/v1/chat |
Streaming chat |
GET /api/v1/workflows/{id}/checkpoints |
List durable checkpoints |
POST /api/v1/workflows/{id}/recover |
Resume from last checkpoint |
GET /api/v1/workflows/{id}/replay |
Audit-grade replay |
CRUD /api/v1/volumes |
Volume management |
CRUD /api/v1/artifacts |
Long-term artifact storage |
GET/POST /api/v1/audit/reviews |
Human-in-the-loop review queue |
Full interactive docs at http://localhost:8000/docs once running.
| Variable | Description | Required |
|---|---|---|
OPENAI_API_KEY |
OpenAI API key | One LLM key required |
ANTHROPIC_API_KEY |
Anthropic API key | One LLM key required |
OPENROUTER_API_KEY |
OpenRouter API key | One LLM key required |
DATABASE_URL |
PostgreSQL connection | Yes |
REDIS_URL |
Redis connection | Yes |
SECRET_KEY |
JWT signing key (≥32 chars) | Yes |
USE_DURABLE_WORKFLOWS |
Enable DBOS checkpointing | No (default True) |
USE_STATE_MACHINE |
Enable state-machine safety layer | No (default True) |
See .env.example and backend/.env.example for the full list.
# Backend
cd backend && pytest
# Frontend
cd frontend && npm testCoverage targets: 70% overall, 90% on critical paths, 95% on agent evaluation suites.
- QUICKSTART.md — local development setup
- TESTING.md — testing strategy
- CONTRIBUTING.md — contribution guidelines
- SECURITY.md — vulnerability disclosure
- In-app docs at
http://localhost:3000/docsonce running
- Zero-trust architecture, ephemeral credentials, 15-minute JWT TTL
- Multi-tenant isolation via PostgreSQL Row Level Security
- RSA-2048-signed audit log with hash chaining
- State-machine safety: invalid tool calls are masked at logit time
- SSRF protection in the OpenAPI connector (private-IP blocking, scheme validation)
- Pydantic schemas validate every API boundary
To report a vulnerability, see SECURITY.md.
Fork, branch, change with tests, open a PR. See CONTRIBUTING.md for the full process.
Guidelines:
- TypeScript strict mode on the frontend
- Async/await for all I/O in the backend
- 70%+ coverage for new features
- Schema changes via
alembic revision --autogenerate
Business Source License 1.1. Source-available — free for non-production, personal, educational, and research use. Production or commercial use requires a separate license. Auto-converts to Apache 2.0 on 2030-05-09. See LICENSE.
For commercial licensing inquiries: balachander.ral@gmail.com
Built with Next.js · React Flow · FastAPI · Pydantic AI · DBOS · E2B · PostgreSQL · Redis