Getting Started

OpenIslands is built for an agent to own a dashboard over months — but you bootstrap it. You scaffold a project, connect your agent to it over MCP, then drive it with prompts. From there the agent reads your data, proposes a change as a full manifest, validates it, and applies it — and can undo any of it. Here's the path from nothing to an agent-maintained dashboard.

Scaffold a project

Pick a template (finance, health, or operations); init drops a complete, working project in the target directory.

npx openislands init my-dashboard --template finance
cd my-dashboard

finance is the flagship: net worth, allocation, holdings, and transactions as typed islands over CSVs you own.

Connect your agent over MCP

Add the @openislands/mcp server to your agent's MCP config, pointed at the project directory (the folder that holds app/manifest.json).

.mcp.json

{
  "mcpServers": {
    "openislands": {
      "command": "npx",
      "args": ["-y", "@openislands/mcp", "."]
    }
  }
}

npx runs the latest published server on demand; its -y flag skips the install prompt, so there's nothing to install globally. The last argument is the project directory — . if your agent runs from inside it.

Serve it so you can watch

npx openislands serve

This renders the dashboard at 127.0.0.1:4321, querying your files on every request. Leave it running — each edit the agent applies live-updates the page over SSE.

Prompt the agent

Now just ask. The agent grounds itself first (it reads the manifest, the dataset schema, and real rows), proposes the full manifest so you see a diff before anything is written, applies it with a snapshot of the prior version, and rolls back if the result is wrong. A binding to a column that doesn't exist comes back as a named error, so a broken dashboard never ships.

Prompts that work well:

Drop data/spending.csv into the project and add a page that charts monthly spend by category.

Give the net-worth KPI a delta against last month, and add a gauge for my savings-rate goal.

That loop runs as long as you keep the agent pointed at the project: it adds islands, wires in new files, and fixes bindings without the app rotting. The same surface drives data writes (actions) and provider syncs (connectors), reversible through the same snapshots.

Where to go next

MCP Server: the agent edit loop in full, and why each guarantee is structural.
CLI: the keyboard path — init, serve, infer, add, validate, sync.
The Manifest: the mental model behind that JSON file.
Islands: the visual building blocks, with live previews.