Let's get biopb running.

Answer a question or two below and you'll get the exact steps for your machine. For most people it's a single copy-paste — with a little extra setup on Windows.

Before you start: make a note of where your image data lives — the folder or drive your microscopy files are in. Partway through, the installer asks for that location in a plain text terminal, so it's smoother if you already have the path handy. Not sure yet? No worries — you can point biopb at your data later too.

First things first — what kind of computer are you on?

You're one command away. 🎉

  1. Install biopb

    Open your Terminal — on Mac, press ⌘ + Space, type “Terminal”, and hit Enter; on Linux you already know where it lives 😉 — then paste this in and press Enter:

    Terminal — Mac / Linux
    $ curl -fsSL https://biopb.org/install.sh | bash

    Let it run. It downloads biopb, sets up its data server, and installs a friendly AI agent (OpenCode). Partway through it'll pause to help you set up a free OpenCode Zen account — just follow the prompt (no credit card, free models included) and paste the key back when it asks. After that you're wired up.

    Never pasted a command like this before? Totally normal. curl … | bash just means “download our little setup script and run it.” Want to read exactly what it does first? It's plain text at biopb.org/install.sh.

  2. Open your agent and ask ✨

    That's it — no server to start. Open your AI agent — Claude Code, OpenCode, or Cursor — and just ask it to open an image or run an analysis. Your agent launches biopb on its own whenever it needs it. That's the whole workflow.

Windows: two solid routes. Pick your vibe. 🪟

Either way you'll install one thing yourself first — that's just how Windows rolls. Choose the one that fits you:

The WSL route 🐧🪟

WSL (Windows Subsystem for Linux) lets Windows run a genuine Linux inside itself. Set it up once, and biopb installs exactly like it does on Mac and Linux.

  1. Turn on WSL

    Click Start, type “PowerShell”, then choose Run as administrator. In the blue window, paste:

    PowerShell (Administrator)
    > wsl --install

    Restart your PC when it asks you to.

  2. Set up Ubuntu

    After the restart, an Ubuntu window opens and asks you to pick a username and password. Choose anything you like — just remember them. (This is your new Linux account; the password won't show as you type, that's normal.)

  3. Grab the basics

    A fresh Ubuntu doesn't ship with curl, so install it first (it'll ask for the password you just created — the typing stays hidden):

    Ubuntu (WSL)
    $ sudo apt update && sudo apt install -y curl

  4. Install biopb

    In that same Ubuntu window, paste the one-liner everyone else uses:

    Ubuntu (WSL)
    $ curl -fsSL https://biopb.org/install.sh | bash

    Partway through, it'll pause to help you set up a free OpenCode Zen account — just follow the prompt (no credit card, free models included) and paste the key back when it asks.

  5. Open your agent and ask ✨

    No server to start — open your AI agent and ask it to load an image or run an analysis. Your agent launches biopb on its own whenever it needs it.

Stuck on the WSL step? Microsoft's short WSL install guide walks through it with screenshots.

The native route 💻

Prefer to stay on plain Windows? You'll talk to biopb through a supported AI agent, and a one-line installer wires biopb straight into it for you.

Quick check — do you already use one of these agents?
OpenCode, Claude Code, Cursor, or Hermes

  1. Run the installer

    Open PowerShell (the normal one — no administrator needed), then paste:

    PowerShell
    > powershell -c "irm https://biopb.org/install.ps1 | iex"

    It finds your agent — OpenCode, Claude Code, Cursor, or Hermes — and connects biopb to it automatically. Nothing to configure by hand.

  2. Open your agent and ask ✨

    No server to start — open your agent and ask it to load an image or run an analysis. Your agent launches biopb on its own whenever it needs it.

  1. Install the OpenCode desktop app

    Download OpenCode for Windows from opencode.ai/download and run the Windows installer (next-next-finish). This is the free chat app you'll talk to biopb through.

    On first launch it'll ask you to connect an AI model. Choose OpenCode Zen and create a free account — no credit card needed, and it comes with a few free models to get you started. (Already have an Anthropic or OpenAI key? You can paste that in instead.)

  2. Run the installer

    Open PowerShell (the normal one — no administrator needed), then paste:

    PowerShell
    > powershell -c "irm https://biopb.org/install.ps1 | iex"

    It finds your OpenCode app and connects biopb to it automatically — nothing to configure by hand.

  3. Open OpenCode and ask ✨

    No server to start — open OpenCode and ask it to load an image or run an analysis. OpenCode launches biopb on its own whenever it needs it.

Curious what that command does? irm … | iex is just PowerShell for “download our setup script and run it.” You can read it first at biopb.org/install.ps1.

Still stuck? We've got you. 🤝

Hit a snag or an error you don't recognize? Open an issue on GitHub (paste the message you saw), or ask the friendly bioimaging crowd on the image.sc forum. No question is too basic.