Startup Config

Define how your project starts with a single JSON file, then run it with one click.

Overview

The .blueberry/startup.json file lives at the root of your project and tells Blueberry how to set up and run it. Think of it as a recipe: install dependencies, start your servers, and open the preview, all automated.

When Blueberry detects a valid startup.json, a Run button appears in the header bar. Clicking it launches your project in app mode: setup commands run first, then all processes start in parallel, and the preview opens automatically once the server is ready.

Since the file lives in your repository, your whole team gets the same one-click setup.

The Config File

Create a .blueberry/startup.json file at the root of your project. It has three fields:

name (optional)

Display name shown in the startup screen and desktop launcher. Defaults to the folder name if omitted.

"name": "My App"

setup (optional)

Array of shell commands to run sequentially before starting processes. If any command fails, startup stops and shows the error. Use this for installing dependencies, running migrations, or building assets.

"setup": [
  "npm install",
  "npm run db:migrate"
]

run (required)

Object of named processes to start in parallel. Each entry needs a command, and exactly one must have preview: true.

Examples

Single Service

A typical setup for a Next.js or Vite project:

{
  "name": "My App",
  "setup": ["npm install"],
  "run": {
    "web": {
      "command": "npm run dev",
      "port": 3000,
      "preview": true
    }
  }
}

Multiple Processes

A full-stack project with a frontend, API server, and background worker:

{
  "name": "Full Stack App",
  "setup": ["npm install", "npm run db:migrate"],
  "run": {
    "frontend": {
      "command": "npm run dev",
      "port": 3000,
      "preview": true
    },
    "api": {
      "command": "npm run api:dev",
      "port": 4000
    },
    "worker": {
      "command": "npm run worker"
    }
  }
}

Minimal

If you just need a dev server with no setup step:

{
  "run": {
    "dev": {
      "command": "npm run dev",
      "preview": true
    }
  }
}

How It Works

When you click Run (or open the project as a desktop app):

1. Startup screen appears, showing the project name and favicon.
2. Setup commands run one at a time. Each must succeed before the next starts.
3. Run processes all start in parallel, each in its own terminal session.
4. Port monitoring watches for the preview process to start listening. Once the port responds, the preview opens automatically.

AI Integration

Claude can create startup.json for you using the blueberry_create_startup_config MCP tool. Ask Claude to set up your project for app mode and it will generate the config based on your project structure.

Worktree Integration

When you create a new worktree in a project that has a startup.json, Blueberry offers to run the setup commands automatically. A toast notification appears after the worktree is created, letting you kick off npm install, migrations, or whatever else is defined in your setup array. This gets every worktree ready to work in without manual steps.

Tips

• Keep setup commands idempotent. Commands like npm install are safe to re-run, which makes the experience smooth even if dependencies are already installed.
• Use port hints. Specifying port avoids the auto-detection delay and makes startup faster.
• Multiple processes are fine. Background workers, API servers, and database tools can all run alongside your preview process.
• Validation is immediate. Blueberry validates the config when the file is saved. If something is wrong (missing preview: true, invalid port, etc.), the Run button won’t appear.