Which surface do I want?
There are four ways to use Biosimulant. They run the same labs on the same runtime, but they sign you in differently and they are not interchangeable. Pick the row that matches what you’re doing.
| Surface | Use it for | How you sign in | It cannot |
|---|---|---|---|
Local CLI (pip install biosimulant) | Building and running labs on your own machine, CI, containers | auth login --web in the browser, or a developer API key — and only for private pulls or publishing | Create account workspaces, managed Runs, or Passports |
| Studio (browser) | Forking a public lab, changing parameters, comparing runs | Your account, in the browser | Run your own uncommitted local files |
| Developer API | Submitting managed runs from your own code | A developer API key in Authorization | Author or compose models |
| MCP (Claude, Codex) | Letting an agent search the Hub, build in a workspace, run on managed compute, and publish | A browser consent flow in your client — no token, no CLI | Nothing runs without your explicit approval |
Connecting an agent
If you want Claude or Codex to use Biosimulant, you want
MCP. You do not need to pip install biosimulant
and you do not need a token. Sign-in happens in your client’s browser
consent flow.
biosimulant auth login is for the local CLI only. It asks for a registry
token because the CLI talks to the Hub’s package registry, which is a different
thing from the agent gateway. Installing the CLI will not connect an agent, and
signing an agent in will not authenticate the CLI.
An agent may still use the CLI once it is connected — a local coding agent with a shell will run labs locally when your machine can handle them, because that is faster and free. That is an optimisation, not a requirement. Nothing an agent needs from your account depends on the CLI being installed.
What each credential is
| Credential | Issued by | Used by | Revoke at |
|---|---|---|---|
Developer API key (bsk_live_…) | Developer console, or biosimulant auth login --web | CLI registry operations, Developer API | Developer console |
| MCP authorization | Browser consent in your agent client | The MCP server only | Connected clients |
Never paste an access token, refresh token, authorization code, or session cookie into a prompt or a project file. The sign-in flows handle credentials so you don’t have to.
Running: local or managed
Both are real, and they produce different things.
- Local —
biosimulant labs run, orBioWorld.run()in Python. Free, offline, no account. Use it for iteration. It produces results on your machine; it does not produce a managed Run or a Passport. - Managed — the Developer API, Studio, or an agent over MCP. Runs on Biosimulant compute with the runtime and inputs recorded, and yields a durable Run you can recover after disconnecting, plus a signed Experiment Passport.
Use local while you’re developing and managed when the result has to be reproducible by someone else. A local run is evidence; it is not a substitute for a managed run that was asked for.
Check whether this machine can run a lab locally at all:
biosimulant labs capabilities ./my-lab --json