UCSF Setup Guide

BioRouter is built for UCSF researchers. Use your institutional AI access for secure, compliant workflows with enterprise-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-hosted Anthropic)

1. Log in via UCSF AWS SSO: aws sso login --profile <your-profile>
2. In BioRouter: Settings → Models → Amazon Bedrock → Configure
3. Set AWS_PROFILE and AWS_REGION when prompted
4. Select Claude Sonnet or another Bedrock-hosted model

Default model: claude-sonnet-4-5. Data stays within UCSF's AWS environment.

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 recommended — but always verify compliance before processing any sensitive data.

Providers & Models

BioRouter connects to a wide range of LLM providers. Switch providers at any time from Settings → Models without changing your workflows.

UCSF Institutional Providers

Commercial Cloud Providers

Local Models — Ollama

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

ollama pull qwen3           # Recommended general-purpose
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 → Select "Configure Providers"

Extensions, Skills & MCP

Extend BioRouter with MCP servers, reusable Skills, and built-in platform capabilities — from database access to browser automation.

Built-in Extensions

Enabling Extensions

Desktop: Sidebar → Extensions → toggle on.
CLI: biorouter configure → Add Extension → Built-in Extension

Adding External MCP Servers

Desktop: Sidebar → Extensions → Add custom extension → enter type, ID, name, command, 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

Skills are reusable .md instruction files that encode your team's workflows and best practices. Drop a skill file in your skills directory and BioRouter makes it callable in any session.

Skills can be shared across a team or institution to standardize analysis pipelines — without sharing any underlying data.

Recipes & Automation

Recipes package any workflow into a shareable, parameterizable, schedulable unit — the foundation of federated research collaboration in BioRouter.

What is a Recipe?

A Recipe is a YAML file that defines a prompt template, input parameters, and an optional schedule. Recipes enable reproducible, shareable workflows that travel across institutions without carrying any data.

Recipe Structure

name: "Literature Review"
description: "Summarize recent papers on a research topic"
parameters:
  - name: topic
    description: "Research topic to review"
    required: true
  - name: years
    description: "How many years back to cover"
    default: "3"
prompt: |
  You are a scientific literature reviewer.
  Summarize key findings on: {{ topic }}
  Cover publications from the past {{ years }} years.
  Focus on clinical relevance and methodology.

Running a Recipe

Desktop: Sidebar → Recipes → select a recipe → fill parameters → Run.

CLI:

biorouter run recipe.yaml --param topic="SPOKE knowledge graph" --param years=5

Scheduling Recipes

Add a schedule field using cron syntax to run a recipe automatically:

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

Scheduled recipes run via BioRouter's background service — even when the desktop app is closed.

Sharing Recipes

Recipe files are plain YAML text. Commit them to a shared repository, publish them on GitHub, or email them. Recipients open them with File → Open Recipe or biorouter run <recipe.yaml>. No data is embedded — only the workflow logic.

Data Privacy Guide

BioRouter routes your inputs to an LLM provider. Privacy properties depend entirely 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 built with a Rust backend and Electron + React frontend, connected via a local REST API.

Three-Layer Design

• Interface — Desktop GUI (Electron + React 19) or CLI, accepts user input and renders responses
• Agent Core — Rust-based reasoning loop managing LLM interaction, tool execution, context, and session state
• Extensions — Pluggable MCP servers providing 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 + React

Desktop app: Electron 39 + React 19 + TypeScript, built with Vite + 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, enabling a growing open ecosystem of research agents.

MCP Agents

BioRouter connects to local and remote MCP agents for specialized research tasks. Browse the curated 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 (requires Python + uv). Install with:

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

Playwright MCP uses npx — requires Node.js: nodejs.org

Available Agents

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