# Explain It Simply — What Is InsForge?

> InsForge in plain language: what problem it solves, the simplest useful mental model, and the three ideas a newcomer must remember before reading anything else.

- Repository: InsForge/InsForge
- GitHub: https://github.com/InsForge/InsForge
- Human wiki: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319
- Complete Markdown: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319/llms-full.txt

## Source Files

- `README.md`
- `docs/introduction.mdx`
- `docs/quickstart.mdx`
- `package.json`
- `turbo.json`

---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [docs/introduction.mdx](docs/introduction.mdx)
- [docs/quickstart.mdx](docs/quickstart.mdx)
- [docs/insforge-instructions-sdk.md](docs/insforge-instructions-sdk.md)
- [docs/mcp-setup.mdx](docs/mcp-setup.mdx)
- [package.json](package.json)
- [turbo.json](turbo.json)
- [docker-compose.yml](docker-compose.yml)
- [backend/src/services/ai/chat-completion.service.ts](backend/src/services/ai/chat-completion.service.ts)
- [backend/src/services/storage/storage.service.ts](backend/src/services/storage/storage.service.ts)
- [backend/src/api/routes/](backend/src/api/routes/)
- [backend/src/services/](backend/src/services/)
</details>

# Explain It Simply — What Is InsForge?

InsForge is an open-source Backend-as-a-Service (BaaS) platform built specifically for AI coding agents. Instead of requiring a developer to manually set up databases, authentication, storage, and APIs, InsForge exposes all of those backend capabilities as tools that an AI assistant can call directly — the agent configures and operates your backend the same way a backend engineer would.

This page explains what InsForge is in plain terms, the single mental model that makes everything click, and the three ideas you need to hold in your head before you read anything else in the codebase.

---

## The Problem InsForge Solves

When you build a full-stack application with an AI coding agent, the agent is excellent at producing frontend code: React components, UI logic, and API calls. The hard part is the backend. Setting up a PostgreSQL database, wiring up authentication, handling file storage, and deploying serverless functions requires deep expertise and many manual steps. Agents historically could generate backend code but could not actually provision or configure the infrastructure it targets.

InsForge closes that gap. It gives AI agents a live, real backend they can read from, write to, and configure — all through a single programmable interface.

Sources: [docs/introduction.mdx:1-30]()

---

## The One Mental Model: A Backend Your Agent Can Drive

Think of InsForge as a backend workbench with two control panels:

```text
┌─────────────────────────────────────────────────────┐
│                 AI Coding Agent                      │
│          (Cursor, Claude Code, Copilot …)            │
└──────────────┬───────────────────┬───────────────────┘
               │                   │
    ┌──────────▼──────┐   ┌────────▼─────────┐
    │   MCP Server    │   │  CLI + Skills     │
    │ (self-hosted    │   │  (cloud only)     │
    │  or cloud)      │   │                  │
    └──────────┬──────┘   └────────┬─────────┘
               │                   │
               └────────┬──────────┘
                        │
          ┌─────────────▼──────────────────────┐
          │           InsForge Backend          │
          │  ┌──────────┐  ┌──────────────┐   │
          │  │PostgreSQL│  │ Auth (JWT +  │   │
          │  │+ PostgREST  │   OAuth)     │   │
          │  └──────────┘  └──────────────┘   │
          │  ┌──────────┐  ┌──────────────┐   │
          │  │  Storage │  │ Edge Funcs   │   │
          │  │(S3-compat│  │ (Deno-based) │   │
          │  └──────────┘  └──────────────┘   │
          │  ┌──────────┐  ┌──────────────┐   │
          │  │Model     │  │  Realtime    │   │
          │  │Gateway   │  │  (WebSocket) │   │
          │  └──────────┘  └──────────────┘   │
          └────────────────────────────────────┘
```

The agent talks to InsForge, and InsForge talks to the infrastructure. The developer never has to become a DevOps expert.

Sources: [README.md:45-80](), [docker-compose.yml:1-65]()

---

## The Three Ideas You Must Know First

### 1. InsForge is a BaaS, not a framework

InsForge is not a library you import into your app code. It is a running service — a backend server — that your application connects to over HTTP or WebSocket. The service exposes a consistent API surface for every primitive you need: a PostgreSQL database, authentication, file storage, serverless functions, realtime pub/sub, and an AI model gateway.

You connect to it using the TypeScript SDK (`@insforge/sdk`), a REST API, a Swift SDK, or a Kotlin SDK, depending on your platform. The pattern is always the same: create a client with your project URL and anon key, then call methods.

```js
// docs/insforge-instructions-sdk.md — Step 3
import { createClient } from '@insforge/sdk';

const client = createClient({
  baseUrl: 'https://your-app.region.insforge.app',
  anonKey: 'your-anon-key-here'
});
```

Sources: [docs/insforge-instructions-sdk.md:18-40]()

### 2. Agents interact through MCP tools or a CLI — not through your app code

The part of InsForge designed for AI agents is separate from the SDK your app uses. Agents get their own interface: an MCP (Model Context Protocol) server. The MCP server exposes backend operations as named tools — `fetch-docs`, `run-migration`, `deploy-function`, `list-buckets`, and so on — that any MCP-compatible agent can call directly, without writing application code.

There is also a CLI (`@insforge/cli`) paired with "Skills" (agent instruction files) for cloud-hosted projects. Both interfaces let the agent read documentation, inspect running state, apply schema migrations, deploy edge functions, and verify that what it built is actually working.

```bash
# quickstart.mdx — Step 2: link a project
npx @insforge/cli link --project-id <your-project-id>
```

Sources: [README.md:32-50](), [docs/quickstart.mdx:30-50](), [docs/mcp-setup.mdx:1-20]()

### 3. The backend is self-hostable and BYOK (Bring Your Own Keys)

InsForge runs inside a Docker Compose stack. The compose file spins up PostgreSQL (custom image `ghcr.io/insforge/postgres`), PostgREST (which turns your database tables directly into REST endpoints), the InsForge API server, and optionally storage. You can run it locally on port 7130, run multiple isolated projects on the same host by giving them different port offsets, or deploy to Railway, Zeabur, or Sealos with one click.

The AI model gateway routes calls through OpenRouter. You supply your own API keys; InsForge does not proxy traffic through a proprietary model provider. Storage defaults to local disk and optionally switches to any S3-compatible endpoint (AWS, Wasabi, MinIO) you configure.

```yaml
# docker-compose.yml — core service wiring
services:
  postgres:   # ghcr.io/insforge/postgres:v15.13.2
  postgrest:  # postgrest/postgrest:v12.2.12 — database-as-API
  insforge:   # the InsForge API + admin UI on port 7130
```

Sources: [docker-compose.yml:1-80](), [backend/src/services/storage/storage.service.ts:1-24](), [backend/src/services/ai/chat-completion.service.ts:1-15]()

---

## What the Backend Actually Provides

The backend is a TypeScript monorepo (`turbo.json`) with these independently structured service areas, each with its own routes and service layer:

| Capability | What it does | Backed by |
|---|---|---|
| **Database** | PostgreSQL tables exposed as REST endpoints; schema migrations via MCP tools | PostgREST + PostgreSQL |
| **Authentication** | Email/password, OAuth (Google, GitHub), OTP, JWT sessions | Custom auth service + OAuth PKCE |
| **Storage** | S3-compatible file upload/download/listing with signed URLs | Local disk or any S3-compatible endpoint |
| **Edge Functions** | Serverless functions deployed and invoked via the API | Deno-based runtime |
| **Model Gateway** | OpenAI-compatible API routing to multiple LLM providers | OpenRouter |
| **Realtime** | WebSocket pub/sub for database events and client messages | Custom socket layer |
| **Site Deployment** | Build and host frontend apps | Deployment service |
| **Compute** | Long-running container services (private preview) | — |

Sources: [backend/src/api/routes/](backend/src/api/routes/), [backend/src/services/](backend/src/services/), [docs/introduction.mdx:30-55]()

---

## How the Codebase Is Structured

The repository is a Turborepo monorepo with three main workspaces:

```text
insforge/
├── backend/          ← Express API server + all service logic
│   └── src/
│       ├── api/routes/   ← HTTP route handlers (auth, db, storage, AI …)
│       ├── services/     ← Business logic per domain
│       ├── infra/        ← Database connection manager, config
│       └── providers/    ← Storage (local/S3) and AI (OpenRouter) adapters
├── frontend/         ← Admin dashboard UI
└── packages/
    ├── shared-schemas/   ← Zod schemas shared between backend and clients
    ├── ui/               ← Shared React component library
    └── dashboard/        ← Dashboard package
```

Turborepo orchestrates builds so that `shared-schemas` is always compiled before the backend or frontend that depends on it. Development runs both backend and frontend concurrently via `npm run dev`.

Sources: [package.json:5-10](), [turbo.json:1-45]()

---

## Getting Started in 60 Seconds

1. **Cloud path**: Create a free project at `insforge.dev`, copy the Project ID, run `npx @insforge/cli link --project-id <id>`, then send the verification prompt to your agent.
2. **Self-hosted path**: `git clone`, `cp .env.example .env`, `docker compose -f docker-compose.prod.yml up` — the admin UI lands on `http://localhost:7130`.
3. **Connect your agent**: Add the MCP server JSON from your project dashboard to Cursor, Claude Code, or any MCP-compatible assistant. The agent can then call `fetch-docs` to read the current instructions and begin building.

Sources: [docs/quickstart.mdx:1-55](), [README.md:82-130]()

---

## Summary

InsForge is an open-source BaaS built so AI coding agents can fully operate a production-grade backend — not just generate code that targets one. It wraps PostgreSQL, authentication, file storage, serverless functions, a multi-provider AI model gateway, and realtime messaging behind a single MCP interface and CLI that any agent can call. It self-hosts with Docker Compose, is provider-neutral (your own LLM keys, your own S3), and ships SDKs for TypeScript, Swift, Kotlin, and plain REST. The three things to hold onto: InsForge is a running service (not a library), agents drive it through MCP tools rather than app code, and the whole stack is self-hostable and BYOK.

Sources: [README.md:1-50](), [docs/introduction.mdx:1-30](), [backend/src/services/](backend/src/services/)