curl -fsSL https://github.com/BaranziniLab/BioRouter/releases/download/stable/download_cli.sh | bash

~/.config/biorouter/config.yaml    # macOS / Linux

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

Field	Environment Variable	Value
Endpoint	AZURE_OPENAI_ENDPOINT	https://unified-api.ucsf.edu/general
Deployment Name	AZURE_OPENAI_DEPLOYMENT_NAME	gpt-5-2025-08-07
API Version	AZURE_OPENAI_API_VERSION	2025-01-01-preview
API Key	AZURE_OPENAI_API_KEY	Your UCSF Versa API key

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 same UCSF MuleSoft gateway used by UCSF Versa. Your data never leaves UCSF's infrastructure.

Step 1 — Obtain Your Credentials

The UCSF Bedrock proxy uses a static AWS Access Key + Secret Key pair — these are not personal AWS SSO credentials. Obtain them from your lab's BioRouter onboarding document or contact the Baranzini Lab / UCSF Research IT for access. You will receive four values:

Credential	Environment Variable	Notes
AWS Access Key ID	AWS_ACCESS_KEY_ID	32-character hex string provided by UCSF
AWS Secret Access Key	AWS_SECRET_ACCESS_KEY	32-character mixed string provided by UCSF
Region	AWS_REGION	us-west-2
Proxy Endpoint	AWS_ENDPOINT_URL_BEDROCK	https://unified-api.ucsf.edu/general/awsai

Step 2 — Configure Credentials

macOS GUI apps (launched from Finder, Spotlight, or Dock) do not inherit your shell's environment variables. For BioRouter to work reliably you need to configure credentials in all three of the following places. The quickest way is the setup script:

Quick Setup — Run the Script

Create a file called setup_bedrock.sh, paste the block below (filling in your credentials), and run it once:

#!/bin/bash
AWS_ACCESS_KEY_ID="<your-access-key-id>"
AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
AWS_REGION="us-west-2"
BEDROCK_ENDPOINT="https://unified-api.ucsf.edu/general/awsai"

# 1. Shell env — picked up by Terminal / CLI
grep -qF "AWS_ACCESS_KEY_ID" ~/.zshrc || cat >> ~/.zshrc <<EOF

export AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
export AWS_REGION=$AWS_REGION
export AWS_ENDPOINT_URL_BEDROCK=$BEDROCK_ENDPOINT
EOF

# 2. ~/.aws files — picked up by GUI apps that skip the shell
mkdir -p ~/.aws
cat > ~/.aws/credentials <<EOF
[default]
aws_access_key_id = $AWS_ACCESS_KEY_ID
aws_secret_access_key = $AWS_SECRET_ACCESS_KEY
EOF
cat > ~/.aws/config <<EOF
[default]
region = $AWS_REGION
EOF

# 3. launchctl — injects vars into macOS at OS level for GUI apps
launchctl setenv AWS_ACCESS_KEY_ID "$AWS_ACCESS_KEY_ID"
launchctl setenv AWS_SECRET_ACCESS_KEY "$AWS_SECRET_ACCESS_KEY"
launchctl setenv AWS_REGION "$AWS_REGION"
launchctl setenv AWS_ENDPOINT_URL_BEDROCK "$BEDROCK_ENDPOINT"

source ~/.zshrc
echo "Done. Restart BioRouter for changes to take effect."

chmod +x setup_bedrock.sh && ./setup_bedrock.sh

Why Three Locations?

Location	What it covers
~/.zshrc exports	Terminal sessions and CLI tools that inherit the shell environment
~/.aws/credentials + config	The AWS SDK's file-based credential chain — used by apps that don't inherit shell env vars
launchctl setenv	Injects vars at the macOS process level — the only reliable way to pass env vars to apps launched from Spotlight, Dock, or Finder

Step 3 — Configure BioRouter

After running the setup script, open BioRouter and point it at the Bedrock provider:

1. Go to Settings → Models → Amazon Bedrock → Configure
2. Confirm the four environment variables are visible — BioRouter reads them automatically
3. Set Model to us.anthropic.claude-sonnet-4-6 (default)
4. Click Launch — send a test message to verify

Available Models

Model	Model ID	Notes
Claude Sonnet 4.6 ⭐ Default	us.anthropic.claude-sonnet-4-6	Best balance of speed and capability
Claude Sonnet 4.0	us.anthropic.claude-sonnet-4-20250514-v1:0	Previous generation Sonnet
Claude Opus 4.5	us.anthropic.claude-opus-4-5-20251101-v1:0	Most capable, slower
Claude Opus 4.1	us.anthropic.claude-opus-4-1-20250805-v1:0	Previous Opus generation

Only models permitted by UCSF's IAM policy are listed — selecting others will result in an authentication error.

Troubleshooting

Error	Cause	Fix
"The security token included in the request is invalid"	BioRouter is hitting real AWS (not the UCSF proxy) — endpoint var missing	Re-run the setup script; quit and relaunch BioRouter
"invalid model identifier"	Model ID missing us. prefix or -v1:0 suffix	Use a model ID exactly as listed in the table above
Auth error in GUI, CLI works fine	launchctl vars not set — GUI app doesn't inherit shell env	Re-run the script, then fully quit and relaunch BioRouter
"AccessDeniedException" on a specific model	Model not permitted by UCSF IAM policy	Switch to one of the four confirmed models above

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

Provider	Access	Default Model
Azure OpenAI (UCSF ChatGPT)	UCSF Versa API key · Setup guide →	gpt-5-2025-08-07
Amazon Bedrock (UCSF Anthropic)	UCSF proxy credentials · Setup guide →	us.anthropic.claude-sonnet-4-6

Commercial Cloud Providers

Provider	Env Variable	Get API Key
Anthropic	ANTHROPIC_API_KEY	platform.claude.com
OpenAI	OPENAI_API_KEY	platform.openai.com
Google Gemini	GOOGLE_API_KEY	aistudio.google.com
X.AI (Grok)	XAI_API_KEY	console.x.ai
OpenRouter	OPENROUTER_API_KEY	openrouter.ai

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

Extension	What It Does	Default
Developer	File operations, shell commands, code search, text editing	✅ On
Computer Controller	Web scraping, file caching, browser automation	Off
Memory	Remembers user preferences and context across sessions	Off
Auto Visualiser	Auto-generates data visualizations from conversation	Off
Chat Recall	Search across all past conversation history	Off
Code Execution	Run JavaScript in a sandboxed environment	Off
Skills	Load and invoke reusable instruction sets	✅ On
Extension Manager	Discover, enable, and disable extensions mid-session	✅ On

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

Provider	Data Stays Within	Best For
Ollama (local)	Your device only — no network	Maximum privacy, air-gapped requirements
UCSF Azure OpenAI	UCSF's Azure tenant	Institution-approved clinical use cases
UCSF Amazon Bedrock	UCSF's AWS environment	Institution-approved clinical use cases
Commercial APIs (personal)	Provider's cloud infrastructure	De-identified or non-sensitive data only

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

Crate	Role
biorouter	Core agent library — loop, providers, sessions, recipes, scheduling
biorouter-server	Local REST API server (biorouterd) the desktop communicates with
biorouter-cli	CLI binary — biorouter session, biorouter configure, etc.
biorouter-mcp	Built-in MCP servers (Developer, Computer Controller, etc.)

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 →