Install Bluebuild for OpenCode

Bluebuild / OpenCode

Build hardware locally. Upload only when you are ready.

OpenCode supplies the model and authors the design. Bluebuild runs locally, validates the wiring, renders the project, and keeps the working files on your machine.

No Bluebuild login for local workNo simulation pathCloud upload is opt-in

Local boundary

OpenCode model

Hardware Intermediate Representation + local MCP

Bluebuild validation + SQLite

forma-project.json

1Check the prerequisites

Bring OpenCode and a model

Bluebuild does not select a server model or replace failed requests with examples. OpenCode must already be installed and authenticated with the provider you want to use.

OpenCode with a configured model provider. A local provider is supported.
Git, Python 3.11+, Node.js 18+, and npm for the local Bluebuild runtime.
Nothing from this setup requires Bun.

2Install and start the local runtime

One command per platform

The installer uses a pinned checkout when `FORMA_OSS_REF` is supplied, reports the installed revision, preserves your OpenCode settings by using a dedicated local workspace, and starts the backend and UI.

Review installer source

macOS / Linux

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/caid-technologies/Forma-OSS/main/scripts/development/install-opencode.sh | bash

Keep this terminal open while the local Bluebuild backend and UI are running.

Windows PowerShell

irm https://raw.githubusercontent.com/caid-technologies/Forma-OSS/main/scripts/development/install-opencode.ps1 | iex

The script uses native PowerShell process and path handling.

Review the installer source before running it. It clones the public repository, installs the local CLI, and starts the local services.

3OpenCode and build

Use the Bluebuild skill

Open a second terminal. The installer creates `~/forma-workspace`, installs the complete shared skill, and configures its local MCP entry. The project is created by your OpenCode model, not by a demo fixture.

Start OpenCode

cd ~/forma-workspace
opencode mcp list
opencode

On Windows, use the PowerShell equivalent below. `opencode mcp list` should show `forma` connected before you start the prompt.

Windows PowerShell

Set-Location "$HOME\forma-workspace"
opencode mcp list
opencode

Real project prompt

Use the Bluebuild hardware skill to build a real 3.3V plant-watering monitor with an ESP32, capacitive soil sensor, OLED status display, and a low-voltage pump driver. Ask only essential clarification questions. Author a complete Hardware Intermediate Representation, call the local Bluebuild compiler, fix every CRITICAL validation finding, and save the final compiled project manifest in the local Bluebuild workspace. Do not use simulation.

The normal path calls `forma.compile_project`, applies deterministic electrical validation, and keeps the final project in the local workspace. There is no simulation fallback.

4Keep or upload

The cloud boundary is explicit

Local generation, validation, rendering, and status do not require an account. Sign in only when you want to send a completed project to Bluebuild.

Opt-in upload

macOS / Linux

forma-oss login
forma-oss projects push --path ~/forma-workspace/<project-id>

The CLI stores the session in the OS credential store and redacts secrets before upload.

Windows PowerShell

forma-oss login
forma-oss projects push --path "$HOME\forma-workspace\<project-id>"

After a successful push, the CLI reports the cloud project URL and keeps local linkage.

About Bluebuild View the source

Troubleshooting

Missing Python or Node

Install Python 3.11+ and Node.js 18+, then rerun the same setup command. The installer leaves existing files untouched when a prerequisite check fails.

Bluebuild is not connected

Keep the installer terminal open and run `opencode mcp list` from `forma-workspace`. The local endpoint is `http://127.0.0.1:8000/mcp`.

OpenCode cannot run the prompt

Authenticate a model provider in OpenCode. Bluebuild does not provide a hidden simulation model or silently substitute an example project.

Upload asks you to log in

That is expected. Run `forma-oss login` only for cloud operations, then rerun the push command.