Micracode
Open-Source AI Web App Builder

Describe an app in natural language and Micracode streams code into an in-browser workspace.
Iterate by chat or edit the code directly in a Monaco editor — everything runs on your laptop.

Your local AI coding workspace — no database, no auth, no cloud.

---

Quick Install

pip install micracode

Requires Python 3.12+. No Node.js, no Docker, no separate frontend setup.

1. Set your API key

OpenCode (LLM gateway via opencode.ai):

export LLM_PROVIDER=opencode
export OPENCODE_API_KEY=your-key
export OPENCODE_BASE_URL=https://opencode.ai/zen/v1    # optional, this is the default
export OPENCODE_MODEL=gpt-5.4                            # optional, defaults to gpt-5.4

Google Gemini (default, free tier available):

export GOOGLE_API_KEY=your-key

OpenAI:

export LLM_PROVIDER=openai
export OPENAI_API_KEY=your-key
export OPENAI_MODEL=gpt-4o

Ollama (local, no API key needed):

export LLM_PROVIDER=ollama
export OLLAMA_MODEL=llama3.2   # any model you have pulled

Or put any of the above in a .env file in your working directory.

2. Start

micracode web

Open http://localhost:8000 — the full UI and API run from the same process.

micracode web --port 9000       # change port
micracode web --host 0.0.0.0   # expose on your local network

3. Build something

• Type a description on the home screen → Micracode generates a working project
• Chat to iterate, edit code in the Monaco editor, and preview your app live
• Projects are saved as plain folders at ~/opener-apps/
• Click the Settings gear in the top-right to manage your API keys from the UI (keys are saved to ~/.micracode/settings.json and override .env values)

---

Getting started & staying tuned with us.

Star us, and you will receive all release notifications from GitHub without any delay!

---

Features

• ** Natural-Language Codegen** — Describe an app in plain English; Micracode streams a working project into the workspace file by file.

• ** Iterative Chat** — Refine your project through conversation. Ask for changes, fixes, or new features and watch them stream in.

• ** In-Browser Monaco Editor** — Edit generated code directly in a full Monaco editor; changes persist to disk.

• ** Pluggable LLM Providers** — Ships with Google Gemini by default; switch to OpenAI, OpenCode (LLM gateway), or local Ollama with one env var. Ollama models are discovered dynamically — no API key required. OpenCode models are fetched live from the gateway, with free models highlighted.

• ** Local-First Storage** — Projects live as plain folders on your filesystem. No database, no auth, no cloud service required.

• ** Streaming Backend** — Server-sent events deliver generated code in real time using a typed stream-event contract shared between web and API.

• ** Snapshots & Prompt History** — Every project keeps its prompt history and snapshots so you can review or roll back.

• ** Settings UI** — Manage your API keys from the browser. A dedicated /settings page lets you switch providers and store keys in ~/.micracode/settings.json, which override .env values. Model lists are fetched live from the gateway, with free models highlighted.

• ** Project Context Menu** — The … button on each recent task opens a dropdown to open in a new tab, copy the project ID, or delete the project. Benign WebContainer stream errors ("Error in input stream") are suppressed with a user-friendly "Connection interrupted. Retry to continue." message. The Retry button properly clears the old stream before resuming the conversation.

---

Tech Stack

Backend

• FastAPI — High-performance Python web framework
• LangChain + Google Gemini / OpenAI / OpenCode / Ollama — Pluggable LLM orchestration (gemini-2.5-flash by default)
• SSE-Starlette — Server-sent events for streaming code generation
• UV — Modern Python package manager
• Pytest — Storage and HTTP test suite

Frontend

• Next.js 15 — React framework with App Router
• React 19 — Latest React with concurrent features
• Tailwind CSS — Utility-first CSS framework
• Radix UI + shadcn/ui — Accessible component primitives
• Monaco Editor — VS Code's editor in the browser
• WebContainer API — Run Node.js apps directly in the browser
• Zustand — Lightweight state management
• ai-sdk — Vercel AI SDK for chat streaming

Tooling

• Bun — JS workspace manager and runtime
• TypeScript — End-to-end type safety, with shared types in packages/shared

---

Development Setup

For contributors and people building from source. If you just want to use Micracode, see Quick Install above.

Prerequisites

• Node.js v22.18.0 (pinned via .nvmrc)
• Bun ≥ 1.1.0
• Python ≥ 3.12 (managed automatically by uv)
• uv ≥ 0.4
• A Google Gemini or OpenAI API key, or a locally running Ollama instance (no API key needed)

Environment Setup

Copy the example env file into the API app and add your key:

cp .env.example apps/api/.env
$EDITOR apps/api/.env

Minimum config (Gemini, the default provider):

LLM_PROVIDER=gemini
GOOGLE_API_KEY=your_gemini_api_key

Or use OpenAI:

export LLM_PROVIDER=openai
export OPENAI_API_KEY=your-key
export OPENAI_MODEL=gpt-4o

Or use a local Ollama model (no API key required):

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2

Ollama models are discovered dynamically from your local daemon — any model you have pulled (ollama pull <model>) will appear in the UI picker automatically.

See docs/configuration.md for the full reference and supported model IDs.

Installation

nvm use                # picks up .nvmrc -> Node 22.18.0
bun install            # JS workspaces (web + shared)
bun run api:install    # Python deps for the API (creates a uv-managed venv)

Running the Application

Start both apps in parallel:

bun run dev

• Web: http://localhost:3000
• API: http://127.0.0.1:8000

Or run them individually:

bun run dev:web        # Next.js only
bun run dev:api        # FastAPI only (uvicorn --reload)

Open http://localhost:3000, type a project description into the prompt box, and you're off. Full walkthrough in Getting Started.

---

Project Structure

micracode/
├── apps/
│   ├── web/                    # Next.js 15 frontend
│   │   ├── src/
│   │   │   ├── app/            # App Router pages
│   │   │   ├── components/     # React components (incl. shadcn/ui)
│   │   │   ├── lib/            # Utilities and clients
│   │   │   └── store/          # Zustand stores
│   │   └── package.json
│   │
│   └── api/                    # FastAPI backend
│       ├── src/micracode_api/
│       │   ├── agents/         # LLM orchestrator, prompts, model catalog
│       │   ├── routers/        # health, models, projects, generate
│       │   ├── schemas/        # Pydantic request/response models
│       │   ├── starter/        # Starter project templates
│       │   ├── config.py       # Settings (env vars)
│       │   ├── storage.py      # Local filesystem project storage
│       │   └── main.py         # FastAPI app entry point
│       ├── tests/
│       └── pyproject.toml
│
├── packages/
│   └── shared/                 # Shared TypeScript types (stream event contract)
│
├── docs/                       # End-user documentation
└── README.md

---

API Endpoints

All endpoints are mounted under /v1.

Method	Endpoint	Description
GET	/v1/health	Service health check
GET	/v1/models	List available LLM models
POST	/v1/generate	Stream code generation events (SSE)
GET	/v1/projects	List all projects
POST	/v1/projects	Create a new project
GET	/v1/projects/{id}	Get a project by id
DELETE	/v1/projects/{id}	Delete a project
GET	/v1/projects/{id}/files	List/read project files
PUT	/v1/projects/{id}/files	Write project files
GET	/v1/projects/{id}/download	Download project as archive
GET	/v1/projects/{id}/prompts	Get prompt history
POST	/v1/projects/{id}/prompts/pop-assistant	Pop last assistant message
GET	/v1/projects/{id}/snapshots	List project snapshots
GET	/v1/settings	Read current user settings (API keys, provider, etc.)
POST	/v1/settings	Update and persist user settings
GET	/v1/settings/models	Fetch available models from a provider gateway

---

Documentation

End-user docs live in docs/:

• Getting Started — install prerequisites, configure an API key, and run the app.
• Configuration — environment variables, switching between OpenAI and Gemini, and supported model IDs.
• Using the Workspace — the home page, chat, editor, and preview panels.
• Projects on Disk — where your generated apps live and how to work with them outside the app.
• Troubleshooting — common errors and how to fix them.
• FAQ — short answers to common questions.

---

Useful Scripts

bun run dev           # web + api in parallel
bun run dev:web       # Next.js only
bun run dev:api       # FastAPI only (uvicorn --reload, 127.0.0.1:8000)
bun run typecheck     # TS across all workspaces
bun run lint          # eslint across workspaces
bun run format        # prettier
bun run test:api      # pytest (storage + HTTP tests)
bun run api:lint      # ruff check
bun run api:format    # ruff format

---

License

This project is licensed under the MIT License.

---

Contributing

Contributions are welcome! Feel free to open issues and pull requests.

---

Join our community Discord