UCSF setup guide

BioRouter is built for UCSF researchers. Use your institutional AI access for secure, compliant workflows with managed models.

Option A: UCSF Versa / Azure OpenAI (recommended)

UCSF's institutional AI platform, accessed via Azure OpenAI. Get your API key at:

ai.ucsf.edu/platforms-tools-and-resources/ucsf-versa

1. In BioRouter, go to Settings, Models, Azure OpenAI, Configure
2. Enter the endpoint and credentials below, then click Save
3. Click Launch to start chatting

Data stays within UCSF's Azure tenant, safe for institution-approved use cases.

Option B: Amazon Bedrock (UCSF MuleSoft proxy)

UCSF provides access to Anthropic Claude models via Amazon Bedrock, routed through the UCSF MuleSoft gateway. Your data does not leave UCSF's infrastructure. BioRouter handles credential configuration for you; you only enter two values.

Step 1: Obtain your credentials

The UCSF Bedrock proxy uses a static AWS Access Key and Secret Key pair. These are not personal AWS SSO credentials. Obtain them from your lab's BioRouter onboarding document or contact the Baranzini Lab or UCSF Research IT for access.

Step 2: Enter credentials in BioRouter

1. Go to Settings, Models, Amazon Bedrock, Configure
2. Enter a Profile Name (any name, e.g., UCSF Bedrock)
3. Enter your AWS Access Key ID
4. Enter your AWS Secret Access Key
5. Click Save. BioRouter writes the necessary credential files and injects environment variables at the OS level.

Step 3: Launch and verify

1. Set Model to us.anthropic.claude-sonnet-4-6 (default)
2. Click Launch and send a test message to verify

Available models

Only models permitted by UCSF's IAM policy are listed; selecting others returns an authentication error.

Troubleshooting

Option C: Local (Ollama, air-gapped)

For maximum privacy. Nothing ever leaves your device:

1. Install Ollama from ollama.com/download
2. Pull a model: ollama pull qwen3
3. In BioRouter, select Ollama as your provider. No configuration needed.

Other institutions

Check with your institution's IT or compliance office for approved AI hosting options. For institutions without managed AI services, commercial API keys (Anthropic, OpenAI) or local Ollama inference are options. Always verify compliance before processing any sensitive data.

Providers and models

BioRouter connects to a range of LLM providers. Switch providers any time from Settings → Models without changing your workflows. Defaults below reflect biorouter v1.75.2.

UCSF institutional providers

Commercial cloud providers

Every provider exposes its full model list once configured — defaults above are what BioRouter selects when no model is specified.

Local models with Ollama

Install Ollama, pull any model, and select Ollama in BioRouter. Everything stays on your machine. Default model: qwen3.

ollama pull qwen3           # General-purpose default
ollama pull llama3.2        # Fast lightweight option
ollama pull deepseek-r1     # Strong reasoning model

Browse all available Ollama models →

Switching providers

Desktop: Settings → Models, select a provider card, Configure or Launch.
CLI: biorouter configure, then Configure Providers

Extensions, skills, and MCP

Extend BioRouter with built-in capabilities, third-party MCP servers, and reusable skill bundles. Defaults reflect biorouter v1.75.2 (ui/desktop/src/built-in-extensions.json).

Built-in extensions

Ship with BioRouter — no install needed. Enable or disable any of them from Settings → Extensions.

Installing a .brxt extension

BioRouter extensions are distributed as .brxt bundles — a zipped manifest plus a Python MCP server entry point. Installation is drag-and-drop; no terminal needed.

1. Download a .brxt file from the BAAM marketplace.
2. In BioRouter, open Settings → Extensions → Add Extension.
3. Drag the .brxt file onto the drop zone (or click Browse file…). BioRouter validates the manifest and previews the extension's name, version, tool count, and any bundled skills.
4. Click Next: Configure → and fill in any required environment variables (API keys, endpoints). Secrets are stored in BioRouter's keyring; non-secret values are written into config.yaml.
5. Click Install. BioRouter unpacks the bundle, runs it via uv run --directory <installDir> <entry_point>, and enables it automatically.

Any bundled skills inside the .brxt are installed alongside the extension and appear under BioRouter → Skills.

Adding an external MCP server manually

Desktop: Settings → Extensions → Add custom extension. Pick the transport (stdio / SSE / streamable HTTP), then enter ID, name, command, args, and env vars.

Config file (~/.config/biorouter/config.yaml):

extensions:
  github:
    name: GitHub
    cmd: npx
    args: [-y, "@modelcontextprotocol/server-github"]
    enabled: true
    envs:
      GITHUB_PERSONAL_ACCESS_TOKEN: "<your_token>"
    type: stdio
    timeout: 300

Skills system

A skill is a folder containing a SKILL.md file with YAML frontmatter (name, description, optional user-invocable) and freeform instructions. BioRouter loads every skill it finds under ~/.config/biorouter/skills/, ~/.claude/skills/, and ~/.config/agents/skills/.

Installing a skill (drag-and-drop)

1. Download a skill .zip from the BAAM marketplace (or write your own SKILL.md).
2. In BioRouter, open Skills → Add Skill.
3. Drag the .zip (bundle of many skills) or a single .md file onto the drop zone. BioRouter parses the frontmatter, previews the skill(s), and on confirmation copies them into ~/.config/biorouter/skills/<slug>/.

Auto-applied skills activate whenever BioRouter encounters a relevant file or task. To bypass the GUI entirely, unzip a bundle and copy the folder into ~/.config/biorouter/skills/ directly — BioRouter picks it up on next launch.

Skill folders are plain text and reproducible. Share them across a lab or institution to standardize analysis style without sharing any underlying data.

Workflows and automation

A Workflow is a portable YAML file that packages a prompt, the extensions and skills it needs, and an optional schedule. Workflows are the foundation of federated research collaboration in BioRouter — instructions travel between institutions, data does not. (Schema reference: crates/biorouter/src/workflow/mod.rs.)

Workflow YAML format

A minimum workflow needs three top-level fields: version, title, description, plus at least one of instructions or prompt. Everything else is optional.

version: 1.0.0
title: Literature review
description: Summarize recent papers on a research topic.

instructions: |
  You are a scientific literature reviewer. Read the user-supplied
  topic, search for relevant publications, and write a structured
  summary focused on clinical relevance and methodology.

prompt: |
  Summarize the past {{ years }} years of work on {{ topic }}.

# pin a provider/model/temperature for reproducibility
settings:
  biorouter_provider: versa_bedrock
  biorouter_model: us.anthropic.claude-sonnet-4-6
  temperature: 0.2

# pre-enable extensions the workflow expects to use
extensions:
  - type: builtin
    name: developer

# activity pills shown while the workflow loads
activities:
  - Fetch papers
  - Summarize findings
  - Cite sources

# typed parameters surfaced in the GUI / CLI
parameters:
  - key: topic
    input_type: string
    requirement: required
    description: Research topic to review.
  - key: years
    input_type: number
    requirement: optional
    default: 3

# compose larger flows from smaller ones
sub_workflows:
  - name: cite-check
    path: ./sub-workflows/cite-check.yaml

# retry policy for transient failures
retry:
  max_attempts: 3

Running a workflow

Desktop: Sidebar → Workflows → select a workflow → fill parameters → Run. To import a workflow file, use Workflows → Import workflow.

CLI:

biorouter run --recipe workflow.yaml --params topic="SPOKE knowledge graph",years=5

Creating a workflow from a session

After an exploratory chat that produced a useful result, open Workflows → Create from session. BioRouter extracts the instructions, the extensions you actually used, and the model you ran on into a fresh YAML file you can edit, share, or schedule.

Scheduling workflows

Schedules are managed separately from the workflow file via BioRouter's scheduler (Sidebar → Schedules → New schedule). Pick a workflow, give it a cron expression, and BioRouter's background service runs it on cadence — even with the desktop app closed.

cron: "0 8 * * 1"   # Every Monday at 8:00 AM

Sharing workflows

Workflow files are plain YAML text. Commit them to a shared repository, publish them on GitHub, or email them. Recipients open them with Workflows → Import workflow or biorouter run --recipe <file.yaml>. No data is embedded — only the instructions, extension list, and parameter schema travel.

Data privacy guide

BioRouter routes your inputs to an LLM provider. Privacy properties depend on which provider you use. Here's how to choose the right one.

Provider privacy properties

Best practices

• De-identify first. Remove names, dates of birth, MRNs, and other identifiers before any AI processing.
• Minimize data exposure. Provide only what's needed for the task.
• Prefer local models for exploratory work with real data.
• Protect your device. Session logs at ~/.config/biorouter/logs/ may contain your inputs.
• Never share sessions that contain patient or sensitive data.
• Always verify with UCSF IT or your compliance office before processing regulated data.

Architecture

BioRouter is a modular, plugin-based system with a Rust backend and an Electron and React frontend, connected via a local REST API.

Three-layer design

• Interface: Desktop GUI (Electron and React 19) or CLI. Accepts user input and renders responses.
• Agent Core: Rust reasoning loop managing LLM interaction, tool execution, context, and session state.
• Extensions: Pluggable MCP servers that provide tools: file system, databases, web, code execution, and custom agents.

Backend Rust workspace

Key dependencies: tokio (async), axum (HTTP), rmcp (Model Context Protocol), serde/serde_json, tiktoken-rs (token counting), sqlx/SQLite (session persistence), minijinja (recipe templates), tokio-cron-scheduler.

Frontend Electron and React

Desktop app: Electron 39, React 19, TypeScript, built with Vite and Electron Forge. Communicates with the local biorouterd REST API.

Model Context Protocol (MCP)

All extensions use MCP, a standard protocol for LLM tool invocation. Any MCP-compatible server (local process or remote HTTP) can be added as a BioRouter extension. This enables a growing open ecosystem of research agents.

MCP agents

BioRouter connects to local and remote MCP agents for specialized research tasks. Browse the agent ecosystem in the BAAM marketplace.

Adding an agent via desktop UI

1. Go to Sidebar, Extensions, Add custom extension
2. Choose type: Command-line (stdio) for local agents or Streamable HTTP for remote
3. Enter the agent name and command (e.g., uvx --from git+https://... agentname)
4. Add any required environment variables
5. Click Add and enable the extension

Adding an agent via config YAML

extensions:
  spokeagent:
    name: SPOKE Agent
    cmd: uvx
    args:
      - --from
      - "git+https://github.com/BaranziniLab/SPOKEAgent"
      - spokeagent
    enabled: true
    type: stdio
    timeout: 300

Remote HTTP agents

extensions:
  remote-agent:
    name: My Remote Research Agent
    url: https://my-agent.example.com/mcp
    type: streamable_http
    enabled: true
    timeout: 300

Prerequisites

Most UCSF agents use uvx, which requires Python and uv. Install with:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: pip install uv

Playwright MCP uses npx, which requires Node.js: nodejs.org

Available agents

Browse all available agents, copy install commands, and find GitHub links in the BAAM marketplace →