InsForge 完整教學|給 AI Agent 的開源後端平台

01這到底是什麼

給 agent 用的整合後端基礎設施。

InsForge 自我定義為「the all-in-one, open-source backend platform for agentic coding」——給 agentic coding 用的開源整合後端平台。它解決的問題很具體:AI coding agent 已能寫前端,但要做出可上線的全端應用,還缺資料庫、認證、檔案儲存、伺服器函式與部署這些後端零件。InsForge 把這些整合成 agent 能直接呼叫的介面,讓 AI 自己擔任後端工程師。

與傳統 BaaS 的差別在介面對象。Supabase、Firebase 的主要使用者是人,操作靠 Dashboard 與 SDK。InsForge 的主要使用者是 AI agent:它透過 MCP server 或 CLI 取得 live schema、logs 與 project context,直接建表、跑 migration、部署 Edge Function、開 storage bucket、配置 OAuth provider。Agent 不只「寫呼叫後端的程式碼」,而是「配置後端本身」。

技術上,InsForge 是 TypeScript 為主(約 92%)的 monorepo,以 Docker Compose 自架,底層用 PostgreSQL 當資料庫、Deno 跑 Edge Functions、Turbo 管理 build。除了開源自架版,官方另提供雲端託管(insforge.dev)。授權為 Apache 2.0。

Connect
Fetch Docs
Migrate
Auth
Functions
Deploy

02自架安裝

Docker Compose 起一台, 再接上 MCP。

自架版只需要兩個前置條件:Docker 與 Node.js。clone repo、複製環境變數、用 production compose 檔啟動,後端就跑起來了。

# 1. clone 並啟動 InsForge 後端
git clone https://github.com/InsForge/InsForge.git
cd insforge
cp .env.example .env
docker compose -f docker-compose.prod.yml up

啟動後開 http://localhost:7130 進 Dashboard,並連上 InsForge MCP Server。連線完成後,在你的 AI agent(Claude Code、Cursor 等)對話框貼這句,讓 agent 自己讀官方指引、開始接管後端:

# 讓 agent 先讀 InsForge 的使用說明
I'm using InsForge as my backend platform, call InsForge MCP's
fetch-docs tool to learn about InsForge instructions.

雲端版:不想自架就用 CLI 登入

若用官方雲端託管(insforge.dev),不必跑 Docker。CLI 版以一行登入建立環境連結,且不依賴 MCP,任何終端機環境都能用:

npx @insforge/cli login

03八大後端服務

一個平台, 裝齊全端後端零件。

InsForge 把一個全端應用會用到的後端能力整合在同一平台,agent 可依需要逐項配置。以下是官方列出的服務。除了 Compute 標註為私有預覽(private preview),其餘皆為一般可用。

Data · 01

Database

PostgreSQL 資料庫

關聯式資料庫,支援 migration 與 pgvector 向量檢索。agent 可直接建表、改 schema、跑 migration。

Identity · 02

Authentication

使用者認證

使用者、session、OAuth、JWT。agent 可配置認證 provider,不必自己手寫登入流程。

Files · 03

Storage

檔案儲存

S3 相容的物件儲存。agent 可建立 bucket、管理檔案,用於上傳與靜態資源。

AI · 04

Model Gateway

模型閘道

OpenAI 相容 API,跨多家 LLM provider 統一介面。應用端用同一套呼叫接不同模型。

Compute · 05

Edge Functions

伺服器函式

以 Deno runtime 執行的 serverless 函式。agent 可直接部署後端邏輯到 edge。

Sync · 06

Realtime

即時同步

資料庫變更訂閱與 pub/sub 訊息,用於即時更新與多端同步場景。

Deploy · 07

Sites

前端部署

前端站台建置與部署,直接連到同平台的後端基礎設施,前後端一處交付。

Compute · 08

Compute

長時容器

長時間執行的容器化工作負載。標註為 private preview,適合非短時函式的服務。

兩種連線模式:MCP 還是 CLI?

agent 操作 InsForge 有兩條路。MCP server 走的是工具呼叫,能給 agent live schema、logs 與 project context;CLI 走終端機登入,不依賴 MCP,任何環境都能用。自架版兩者皆可,CLI + Skills 目前為雲端限定。

面向	MCP Server	CLI + Skills
連線方式	編輯器 MCP client 連到 server	`npx @insforge/cli login`
agent 取得的內容	live schema、logs、project context	終端環境連結,呼叫 skills
是否依賴 MCP	是	否,任何終端皆可
可用環境	自架 + 雲端	雲端限定

04上手設定 · 依官方文件

接上之後, 先把這幾件事設好。

以下設定要點整理自 InsForge 官方 README 與文件。重點是讓 agent 先讀對指引、用對連線模式,再開始建後端;細節以 docs.insforge.dev 為準。

第一步永遠是 fetch-docs

連上 MCP 後,先讓 agent 呼叫 fetch-docs 工具讀官方指引,再做任何後端操作。官方建議的開場白就是「call InsForge MCP's fetch-docs tool to learn about InsForge instructions」。

來源 · 官方 README · Quickstart

給 LLM 看的文件用 llms.txt

完整平台文件另有彙整版 https://docs.insforge.dev/llms.txt,專供模型讀取。把它餵給 agent,比逐頁爬文件更省 token、也更完整。

來源 · 官方文件 Introduction

自架先確認連接埠 7130 沒被佔

Dashboard 預設開在 http://localhost:7130。若埠衝突或要跑多專案,改 .env 裡的 APP_PORT、POSTGRES_PORT、DENO_PORT 等變數再啟動。

來源 · 官方 README · Self-Hosting

多專案用 --env-file 加 -p 隔離

同機跑多個後端時,各專案複製獨立的 .env.projectN 並指定不同埠,再以 docker compose --env-file .env.project1 -p project1 up -d 分別啟動,容器與資料互不干擾。

來源 · 官方 README · Multiple Projects

不想自架就用 npx CLI 登入

雲端版用 npx @insforge/cli login 即可建立環境連結,不必跑 Docker,也不依賴 MCP。適合在 CI 或不便起容器的終端環境快速接上。

來源 · 官方文件 · CLI

向量檢索直接用內建 pgvector

資料庫支援 pgvector,要做 RAG 或語意搜尋不必另接向量資料庫,在同一個 PostgreSQL 建向量欄位即可,搭配 Model Gateway 產生 embedding。

來源 · 官方文件 · Database

05實戰範例

看 agent 怎麼從零長出後端。

以下是一段示意對話:你要做一個有登入、貼文與圖片上傳的應用。InsForge 後端已用 Docker 起好、MCP 也接上。看 agent 怎麼先 fetch-docs 讀指引,再建表、配認證、開 storage bucket、部署 Edge Function,把後端一步步配置完成。流程依官方文件示意,實際輸出依你的 agent 與專案而定。



$ You ›
  I'm using InsForge as my backend platform, call InsForge MCP's
  fetch-docs tool to learn about InsForge instructions.


# [mcp: insforge · calling fetch-docs]
# [loaded platform docs · database, auth, storage, functions]


claude: Agent ›
  已讀取 InsForge 指引。你的應用需要:使用者登入、貼文、
  圖片上傳。我會依序配置後端,每一步透過 MCP 直接操作:
    1. 建 users / posts 資料表(含 migration)
    2. 開 email + OAuth 認證
    3. 建 storage bucket 收圖片
    4. 部署一支產生貼文摘要的 Edge Function


$ You › go ahead.


# [mcp: run-migration · create table "posts"]
  hl: → posts(id, author_id, body, image_url, created_at) 已建立
# [mcp: configure-auth · providers: email, google]
  hl: → JWT + session 已啟用,OAuth callback 已設定
# [mcp: create-bucket · name "post-images"]
  hl: → S3 相容 bucket 已就緒,public read 已開


claude: Agent ›
  後端骨架已配置完成。接著部署一支 Edge Function,
  用 Model Gateway 幫每篇貼文產生一句摘要。


# [mcp: deploy-function · name "summarize" · runtime deno]
    calls Model Gateway (OpenAI-compatible) → 1 句摘要
ok: → deployed · https://<project>/functions/summarize


claude: Agent ›
  後端就緒。前端用標準 fetch 呼叫即可,無須再寫伺服器:
    · 登入 → auth endpoint
    · 發文 → insert into posts
    · 上傳圖 → post-images bucket
    · 摘要 → /functions/summarize


$ You › verify it from the dashboard.


# [open http://localhost:7130 · schema + logs visible]
ok: tables: 2 · auth providers: 2 · buckets: 1 · functions: 1
ok: 後端全部由 agent 配置,未手寫任何 server 程式碼。

後端全部由 agent 透過 MCP 配置, 建表、認證、儲存、函式一次到位, 未手寫任何伺服器程式碼。

— InsForge 的定位:讓 AI agent 擔任後端工程師

這段流程的關鍵在哪

關鍵不在 agent「會寫呼叫後端的程式碼」,而在它能配置後端本身。透過 MCP 工具,agent 直接跑 migration、開認證、建 bucket、部署函式,並能讀回 live schema 與 logs 確認結果。後端不再是人在 Dashboard 手動點出來的,而是 agent 依需求生出來的。

對開發者而言,這把全端開發收斂成一件事:把意圖講清楚。資料庫、認證、儲存、模型閘道、Edge Functions 都在同一平台,省去逐項串接不同 SaaS 的整合成本。

06先看清楚這些

上手前, 知道這些邊界。

警告

**自架需要 Docker 與 Node.js。**自架版以 Docker Compose 運行,底層含 PostgreSQL 與 Deno。不想維運容器,改用雲端版(insforge.dev)以 npx @insforge/cli login 接入較省事。
**CLI + Skills 目前雲端限定。**MCP server 自架與雲端都支援,但 CLI + Skills 模式目前只在雲端版提供。選連線方式前先確認你的部署形態。
**Compute 仍是 private preview。**長時容器(Compute)標註為私有預覽,功能與可用性可能變動。生產環境的長時工作負載先評估,別預設它已穩定。
**Model Gateway 需自備 provider 金鑰。**模型閘道提供 OpenAI 相容的統一介面,但實際呼叫的 LLM 仍由你接的 provider 計費。閘道整合呼叫,不代表免費用量。
**多專案務必改埠避免衝突。**同機跑多份後端時,沒改 POSTGRES_PORT、APP_PORT、DENO_PORT 等變數會直接埠衝突啟動失敗。複製獨立 .env 並逐一指定。
**agent 直連後端,權限要收斂。**agent 能跑 migration、改認證、開 bucket,等於握有後端配置權。在接近生產的環境授權前,先確認它操作的是預期專案與資料,別把正式庫交給未受限的 agent。
**讓 agent 先 fetch-docs 再動手。**跳過讀指引直接叫 agent 建後端,容易產生與平台慣例不符的 schema 或配置。官方流程把 fetch-docs 放第一步是有原因的。
**授權是 Apache 2.0,先確認合規。**自架與商用前確認 Apache 2.0 條款符合你的需求。雲端託管另有計費,評估時把自架維運成本與託管費一起算。

07進階路徑

從跑起來, 到接進你的應用。

後端起好、agent 接上之後,下一步是把它接進真實專案並擴充能力。以下方向皆對應官方提供的功能。

進階方向

**1. 選好前端框架再接後端。**InsForge 支援 Next.js、React、Vue、Nuxt、Svelte。先決定前端,再讓 agent 依框架慣例串接認證與資料層。

**2. 用 Edge Functions 放後端邏輯。**需要伺服器端運算(webhook、第三方串接、AI 後處理)時,讓 agent 部署 Deno Edge Function,而非把邏輯塞進前端。

**3. 用 Model Gateway 統一接 LLM。**應用要呼叫 LLM 時走 Model Gateway 的 OpenAI 相容介面,日後換 provider 不必改應用端程式碼。

**4. Realtime 做即時更新。**需要多端同步、即時通知或協作功能時,用內建的資料庫變更訂閱與 pub/sub,而非自行架 WebSocket 層。

**5. 用 Sites 一處交付前後端。**前端站台可直接部署並連回同平台後端,省去額外的 hosting 與環境串接。要 scale 長時服務再評估 Compute(private preview)。

延伸閱讀

① docs.insforge.dev/introduction——平台總覽、八大服務與連線模式。 ② docs.insforge.dev/llms.txt——給 agent 讀的完整文件彙整版。 ③ github.com/InsForge/insforge——原始碼、自架設定與 Docker Compose 檔。

The all-in-one, open-source backend platform for agentic coding.

— InsForge,GitHub README

全站搜尋

給 AI Agent 的開源後端平台。

給 agent 用的整合後端基礎設施。

Connect

Fetch Docs

Migrate

Auth

Functions

Deploy

Docker Compose 起一台, 再接上 MCP。

雲端版:不想自架就用 CLI 登入

一個平台, 裝齊全端後端零件。

PostgreSQL 資料庫

使用者認證

檔案儲存

模型閘道

伺服器函式

即時同步

前端部署

長時容器

兩種連線模式:MCP 還是 CLI?

接上之後, 先把這幾件事設好。

第一步永遠是 fetch-docs

給 LLM 看的文件用 llms.txt

自架先確認連接埠 7130 沒被佔

多專案用 --env-file 加 -p 隔離

不想自架就用 npx CLI 登入

向量檢索直接用內建 pgvector

看 agent 怎麼從零長出後端。

這段流程的關鍵在哪

上手前, 知道這些邊界。

從跑起來, 到接進你的應用。

進階方向

延伸閱讀

Connect

Fetch Docs

Migrate

Auth

Functions

Deploy

雲端版:不想自架就用 CLI 登入

PostgreSQL 資料庫

使用者認證

檔案儲存

模型閘道

伺服器函式

即時同步

前端部署

長時容器

兩種連線模式:MCP 還是 CLI?

第一步永遠是 fetch-docs

給 LLM 看的文件用 llms.txt

自架先確認連接埠 7130 沒被佔

多專案用 --env-file 加 -p 隔離

不想自架就用 npx CLI 登入

向量檢索直接用內建 pgvector

這段流程的關鍵在哪

進階方向

延伸閱讀

相關文件

地端 Claude 開發部署手冊|GitHub × Vercel × Cloudflare 標準工作流

把 Mac mini 變成 Jarvis|用 Hermes Agent 連接 Gmail、Slack 與整台主機的常駐代理設定手冊

剪映 Agent 剪輯技能 完整教學|讓 AI 自動完成配音、字幕、配樂與匯出

剪映 Agent 剪輯技能完整教學|讓 AI 自動完成配音、字幕、配樂與匯出