insta-oss

An open-source, self-hostable platform for your database, object storage, and any compute container. Branchable end to end: the most agent-native way to develop.

project = a Postgres database + an S3 bucket + your app containers
branch  = a disposable, fully isolated clone of all three

Quick start · insta CLI · Hosted InstaCloud · Discord

Overview

insta-oss is a single daemon on your own Docker: single-tenant, no accounts, no billing. A project provisions real resources, and everything it creates is plain Docker (a standard Postgres container, an S3-compatible bucket, your own app images). There is nothing proprietary to migrate out of.

InstaCloud is the corresponding hosted service from InsForge: the same insta CLI, MCP server, and agent skills drive both, so workflows move between them unchanged.

What makes it different

A branch is a whole environment, cloned. insta branch create copies the database (with data), copies the bucket, and redeploys every app container, each branch on its own URL, ready in seconds. Break it, throw it away; the source is never touched. One task, one branch, many in parallel.

Governance at the credential boundary. The daemon is the only thing holding credentials, and every sensitive action passes an allow / deny / approve gate before it touches a resource. Agents propose, humans approve: a gated action parks until someone runs insta approvals approve; an agent that ignores its instructions still cannot get past it. Every action lands in the insta events audit timeline.

Features

• Deploys: insta deploy --image you/app or insta deploy ./dir (built locally); redeploy = replace, credentials injected.
• Secrets: one seam of standard DATABASE_URL / AWS_* env vars, scoped project → branch → service; apps need no insta-specific code.
• Managed databases: private Redis / MySQL / MongoDB containers per branch.
• Observability: insta logs / insta metrics per container, plus live Postgres insight (connections, cache-hit, running queries, top statements).
• Audit timeline: every resource and governance action in insta events.
• Dashboard: a web UI served by the daemon itself, approvals inbox included.
• Agent-native: project create installs the agent skills into your repo; insta-mcp works against the daemon.

Quick start

Prerequisites: Docker (running) and Node ≥ 22. Nothing else: no cloud account, no API keys.

git clone https://github.com/InsForge/insta-oss.git && cd insta-oss
npm install
npm run build:ui        # optional: the web dashboard, served by the daemon itself
npm run dev             # the daemon, on http://127.0.0.1:8080  (INSTA_OSS_PORT to change)

First run pulls postgres:16-alpine, dxflrs/garage, and rclone/rclone; give it a minute. State lives in ~/.insta-oss/.

In another terminal, install the CLI and point it at the daemon:

curl -fsSL agents.instacloud.com | sh          # CLI + agent skills (or: npm install -g insta)
export INSTA_API_URL=http://127.0.0.1:8080     # the CLI defaults to the cloud

No insta login: the daemon trusts localhost.

What it looks like

$ cd ~/my-app                       # the CLI links the project to your cwd
$ insta project create demo
created project 4496c3e1-… (demo)
  resources: postgres, storage, compute

$ insta secrets --print             # the only way credentials leave the daemon
DATABASE_URL="postgres://postgres:insta@io-demo-main-pg:5432/app"
AWS_ACCESS_KEY_ID="GK…"  AWS_SECRET_ACCESS_KEY="…"  AWS_ENDPOINT_URL_S3="http://io-garage:3900"
BUCKET_NAME="io-demo-main"

$ insta deploy --image nginx:alpine --port 80
deployed nginx:alpine -> http://localhost:80 (branch main, group default)

$ insta branch create feat          # copies the db + bucket, redeploys the app
created branch feat                 # feat's app: http://localhost:1080 (host port +1000)

$ insta policy set deploy approve   # gate deploys behind a human
$ insta deploy --image nginx:alpine --port 80
approval required for deploy — run: insta approvals approve 7c3c9b68-…

$ insta branch delete feat          # done with the task: throw the clone away

insta manifest shows each branch's db / storage / compute and their URLs.

How it works

Every request flows CLI/MCP/dashboard → HTTP server (routes + govern gate) → engine → an adapter → Docker:

• engine (src/engine.ts): project and branch lifecycle, from provision through clone (pg_dump → restore, rclone sync, app redeploys) to teardown with compensation on failure.
• govern (src/govern.ts): the policy engine, with 12 gated actions, allow/deny/approve per project, one-shot grants, and an HTTP 202 approval flow.
• adapters (src/adapters/): swappable providers behind small contracts. LocalPostgres (a container per branch), LocalGarage (one shared S3 server; a bucket + bucket-scoped key per branch), DockerCompute (your image per compute group), LocalManagedDb (private Redis/MySQL/MongoDB containers per branch). RailwayCompute (INSTA_OSS_COMPUTE=railway) runs compute on Railway instead; proof the seam holds.
• state (src/state.ts): a single JSON file, ~/.insta-oss/state.json.

Command-by-command CLI and MCP compatibility tables: docs/compatibility.md.

Dashboard

The daemon serves a web UI at its own URL: one process, same origin, no login. Services, environments, logs, secrets, database insight, operations, usage, an approvals inbox, and the governance policy matrix; gated actions from the UI go through the same 202 → approve flow as the CLI.

npm run build:ui once, then open http://127.0.0.1:8080. UI development: cd ui && npm run dev (Vite on :5173, proxying API calls to the daemon).

Using it with agents

insta project create (or link) installs the insta agent skills into your project (gitignored; .claude/skills/ for Claude Code, .agents/skills/ for Codex), so a coding agent opened in the repo already knows the workflow: one task → one branch → deploy → verify → delete. You keep the approval power (insta policy set <action> approve) and the audit trail (insta events). The insta-mcp server is a thin client over the same endpoints; point it at the daemon with PLATFORM_API_URL=http://127.0.0.1:8080.

Tests

npm test    # API-contract tests (fake adapters, no Docker) + real-Docker isolation tests

The isolation tests prove clone independence for real: writes to a branch's database and bucket never reach the source.

Cleanup

insta project delete                                   # per project (approval-gated)
docker ps -aq --filter name=io- | xargs docker rm -f   # every insta-oss container
docker volume rm io-garage-meta io-garage-data         # the shared storage server's data
rm -rf ~/.insta-oss                                    # daemon state

Templates

A template is one folder in templates/ describing an app someone can deploy in a single command: a manifest pinning the image and declaring its variables, plus a README and a logo. The published ones show up in the gallery.

Adding one is a single pull request here. templates/README.md has the layout, and templates/AGENTS.md has the rules CI enforces.

Contributing

See CONTRIBUTING.md for the code map and the rules every change follows. Two good entry points: a provider adapter (implement one interface from src/types.ts as a new file in src/adapters/, wire it in src/main.ts, and nothing else changes), or a template, which needs no knowledge of the daemon at all.

Community

• Discord: questions and support
• X / Twitter: release updates
• info@insforge.dev

License

Apache-2.0. See LICENSE.