Setup & onboarding

Hybrid mode keeps inference on your home GPU (Ollama + gateway + Cloudflare Tunnel) while the entity worker runs on Railway with Postgres. This page walks through the interactive wizards that configure .env, automate tunneling, and push Railway variables — no wall of manual commands unless you want it.

What you get

Home brain

Ollama, the inference gateway (default 127.0.0.1:8010), and a tunnel that exposes only the gateway — not a generic reverse proxy.

Cloud body

Worker + API on Railway, Postgres for memory, optional volume for knowledge.md / workspace under /app/data.

One shared secret

A gateway token in .env and on Railway so the worker can call your tunnel over HTTPS with Authorization: Bearer.

How the pieces connect

Why a gateway instead of exposing Ollama directly?

The gateway enforces bearer auth and scopes traffic to inference routes. The tunnel should terminate at the gateway, not at a broad reverse proxy that might expose other services.

Do I need API keys for inference?

No for the default path — Ollama runs on your machine. Optional keys (e.g. Firecrawl, S3) are separate and prompted only if you opt in.Optional: If you want to evaluate the harness against hosted frontier models (OpenRouter, Venice AI), you can set provider + API key — same open codebase, opt-in only. See Hosted inference (testing).

Prerequisites

Repo & Python

Clone Bumblebee, install deps (e.g. uv sync or pip install -e .). Python 3.11+ required.For the gateway: pip install 'bumblebee[gateway]'.

Ollama & models

Install Ollama and pull models matching your harness config (e.g. gemma4:26b, nomic-embed-text). See Hardware for VRAM guidance.

Cloudflare (hybrid)

A DNS zone on Cloudflare for the public hostname you will route to the tunnel (e.g. inference.example.com). You will log in once with cloudflared tunnel login (browser).

Railway (hybrid)

Install the Railway CLI, run railway login, and create or select a project with services that match this repo’s deploy (e.g. bumblebee-worker, bumblebee-api) and a Postgres plugin. Then railway link from the repo root.

Choose your path

Full hybrid (recommended)
Gateway only
Local-only

From the repo root:

bumblebee setup

The wizard asks whether to use hybrid (default) or local. Hybrid runs the full flow: token, tunnel URL, .env, optional stack start, readiness checks, Railway variables, volume hint, and optional deploy.To skip the profile question:

bumblebee setup --profile hybrid

If you only need the home inference stack (tunnel + token + .env) without Railway:

bumblebee gateway setup

This uses the same tunnel automation as hybrid setup. When the repo includes the helper script for your OS, run bumblebee gateway on after. See Gateway.

Single machine, no tunnel:

bumblebee setup --profile local

Configures local inference and optional bot tokens. For day-to-day local use, Quickstart may be enough.

What happens inside `bumblebee setup` (hybrid)

Readiness panel

The wizard prints a checklist: cloudflared on PATH, Cloudflare cert (~/.cloudflared/cert.pem), tunnel config, Railway CLI, railway login, and railway link in this directory. Each line shows how to fix what is missing.

Gateway token

If .env has no token, the wizard offers to generate a random secret (INFERENCE_GATEWAY_TOKEN and BUMBLEBEE_INFERENCE_GATEWAY_TOKEN). The same value must reach Railway — the wizard can set it via stdin when you apply variables.

Public URL (tunnel)

If ~/.cloudflared/config.yml already has a hostname: ingress, the wizard can reuse it. Otherwise it can run automated tunnel setup:

cloudflared tunnel login if needed (browser)
create or reuse a named tunnel
cloudflared tunnel route dns for your FQDN
write config.yml with ingress → http://127.0.0.1:8010 (or your --gateway-host / --gateway-port)

You can also paste a URL manually or use --skip-tunnel-bootstrap to do everything by hand.

`.env` and optional extras

Hybrid keys (BUMBLEBEE_DEPLOYMENT_MODE, BUMBLEBEE_INFERENCE_PROVIDER, BUMBLEBEE_INFERENCE_BASE_URL, etc.) are merged into .env. Optional prompts: Firecrawl, local Postgres URL, S3 for durable attachments on Railway.

Optional hosted inference (OpenRouter / Venice)

After the hybrid or local profile, the wizard may offer OpenRouter or Venice for product-style harness testing: it writes BUMBLEBEE_INFERENCE_PROVIDER, the provider API key, and BUMBLEBEE_INFERENCE_PASS_NUM_CTX=false into .env. Skip this to keep the default local / gateway brain. If you use Railway, mirror the same inference variables and key on bumblebee-worker (and bumblebee-api if needed). Details: Hosted inference (testing).

Home stack (one-command start)

If scripts/gateway.ps1 (Windows) or scripts/gateway.sh (macOS/Linux) is present, you can start Ollama + gateway + cloudflared in one step via bumblebee gateway on. Otherwise run the three processes manually (see Gateway).

Health checks

The wizard can GET /health on the local gateway and on the tunnel URL with your bearer token, so you can confirm the chain before touching Railway.

Entity

If you have no entity YAML yet, you can run bumblebee create from the wizard. Otherwise pick an existing entity name for Railway’s BUMBLEBEE_ENTITY.

Railway

If the CLI is logged in and linked, the wizard can:

set DATABASE_URL from Postgres using ${{ServiceName.DATABASE_URL}}
set hybrid inference variables on bumblebee-worker and bumblebee-api
set BUMBLEBEE_INFERENCE_GATEWAY_TOKEN via stdin (secret)
optionally create a volume at /app/data and set BUMBLEBEE_EXECUTION_WORKSPACE_DIR
optionally run railway up for worker and API

If anything fails, it prints a copy-paste cheat sheet of commands.

Automation vs manual

Step	Automated by wizard	You still do
Generate gateway token	Yes (optional)	Store / rotate secrets if you replace them later
Cloudflare browser login	Launched	Complete OAuth in browser
Tunnel + DNS + `config.yml`	Yes (optional)	Own the zone on Cloudflare; pick hostname
`railway login` / `railway link`	Commands offered	Complete browser / project selection
Postgres + service names	Variables reference your plugin name	Create services & plugin in Railway dashboard
Deploy	Optional `railway up`	Confirm billing / project scope

Agents and CI cannot finish browser OAuth for you. After one-time login on your machine, scripts can run railway variable set and railway up non-interactively. There is no --non-interactive flag for the whole wizard today — use flags like --skip-tunnel-bootstrap and prefill .env for automation.

CLI flags (reference)

`bumblebee setup`

Flag	Purpose
`--profile ask \| hybrid \| local`	Skip or choose the hybrid vs local path (`ask` is default).
`--gateway-host`	Host the gateway listens on (default `127.0.0.1`); used when writing tunnel config.
`--gateway-port`	Port (default `8010`).
`--skip-tunnel-bootstrap`	Do not offer automated `cloudflared` tunnel + DNS + config.

`bumblebee gateway setup`

Flag	Purpose
`--tunnel-name`	Default tunnel name for `gateway on` (default `bumblebee-inference`). Match the tunnel you created.
`--cloudflared-config`	Path to `config.yml` if not `~/.cloudflared/config.yml`.
`--gateway-host` / `--gateway-port`	Same as setup.
`--skip-tunnel-bootstrap`	Manual tunnel only.

Full command list: CLI reference.

Troubleshooting

Tunnel health fails but local health works

Usually cloudflared is not running, ingress points at the wrong host/port, or DNS has not propagated. Confirm config.yml sends your hostname to http://127.0.0.1:8010 (or your chosen port). Restart the tunnel after edits.

Railway worker cannot reach inference

Check BUMBLEBEE_INFERENCE_BASE_URL (scheme https, no path) and that BUMBLEBEE_INFERENCE_GATEWAY_TOKEN exactly matches .env. Test from your laptop: curl the tunnel /health with Authorization: Bearer.

Preflight shows Railway not linked

Run railway link from the repository root (same folder as railway.json). Pick the project that contains bumblebee-worker and bumblebee-api.

gateway on does not match tunnel name

After automated tunnel creation, use the same tunnel name the wizard printed, e.g. bumblebee gateway on --tunnel-name bumblebee-inference (or whatever name you chose). Applies on every OS that uses the gateway helper scripts.

Hybrid Railway overview

Architecture, execution mode, and manual env var reference.

Inference gateway

Gateway env vars, gateway on/off/status, and security notes.

Persistence on Railway

Volumes, workspace dir, and durable files across redeploys.

Environment variables

Full .env and Railway variable reference.

Documentation Index

​What you get

Home brain

Cloud body

One shared secret

​How the pieces connect

​Prerequisites

​Choose your path

​What happens inside bumblebee setup (hybrid)

​Automation vs manual

​CLI flags (reference)

​bumblebee setup

​bumblebee gateway setup

​Troubleshooting

​Related docs

Hybrid Railway overview

Inference gateway

Persistence on Railway

Environment variables

What you get

How the pieces connect

Prerequisites

Choose your path

What happens inside `bumblebee setup` (hybrid)

Automation vs manual

CLI flags (reference)

`bumblebee setup`

`bumblebee gateway setup`

Troubleshooting

Related docs