getting-started.md

Getting Started

This guide walks you from a clean machine to a running Micracode instance with your first project open in the workspace.

1. Install prerequisites

Tool	Version	Install
Node	v22.18.0	nvm: nvm install 22.18.0 && nvm use
Bun	>= 1.1.0	bun: curl -fsSL https://bun.sh/install | bash
Python	>= 3.12	Managed automatically by uv
uv	>= 0.4	uv: curl -LsSf https://astral.sh/uv/install.sh | sh

The repo's .nvmrc pins the Node version, so nvm use from the project root picks the right one.

2. Get the code

git clone <your fork or the upstream repo> micracode
cd micracode
nvm use

3. Install dependencies

# JavaScript workspaces (web + shared)
bun install

# Python deps for the API (creates a uv-managed venv)
bun run api:install

4. Add an API key

Micracode ships with .env.example at the repo root. Copy it into apps/api/.env and fill in one provider's key:

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

Minimum to get going with the default provider (Gemini):

LLM_PROVIDER=gemini
GOOGLE_API_KEY=your-gemini-key

Prefer OpenAI? Set LLM_PROVIDER=openai and provide OPENAI_API_KEY + OPENAI_MODEL. See Configuration for the full reference and the list of accepted model IDs.

5. Run both apps

bun run dev

This starts the Next.js web app and the FastAPI backend in parallel:

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

You should see logs from both processes in the same terminal. Leave it running.

6. Create your first project

1. Open http://localhost:3000.
2. On the home page, type a one-line description of what you want to build into the prompt box and submit.
3. You'll be taken to the workspace, where the chat panel, file tree, editor, and preview are visible. Generated files appear in the tree as the model streams them in.
4. Use the chat panel to iterate — ask for changes, fixes, or new features. Edits you make in the Monaco editor are saved to disk.

That's it. Your project's source files now live under ~/opener-apps/ — see Projects on Disk for the layout.

What's next

• Using the Workspace — tour the UI and the three panels.
• Configuration — change models, providers, ports, or storage location.
• Troubleshooting — if something didn't start.