> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & onboarding

> Guided `bumblebee setup` and `bumblebee gateway setup` — hybrid stack, Railway, Cloudflare Tunnel, and health checks.

<Tip>
  **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.
</Tip>

## What you get

<CardGroup cols={3}>
  <Card title="Home brain" icon="house">
    Ollama, the inference gateway (default `127.0.0.1:8010`), and a tunnel that exposes **only** the gateway — not a generic reverse proxy.
  </Card>

  <Card title="Cloud body" icon="cloud">
    Worker + API on Railway, Postgres for memory, optional volume for `knowledge.md` / workspace under `/app/data`.
  </Card>

  <Card title="One shared secret" icon="key">
    A **gateway token** in `.env` and on Railway so the worker can call your tunnel over HTTPS with `Authorization: Bearer`.
  </Card>
</CardGroup>

## How the pieces connect

```mermaid theme={null}
flowchart LR
  subgraph home [Your PC]
    O[Ollama]
    G[Inference gateway]
    CF[cloudflared]
    O --> G
    G --> CF
  end
  subgraph cloud [Cloudflare]
    T[Tunnel edge]
  end
  subgraph railway [Railway]
    W[bumblebee-worker]
    P[(Postgres)]
    W --> P
  end
  CF --> T
  T -->|HTTPS /health| G
  W -->|Bearer token| T
```

<AccordionGroup>
  <Accordion title="Why a gateway instead of exposing Ollama directly?" icon="shield-halved">
    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.
  </Accordion>

  <Accordion title="Do I need API keys for inference?" icon="key">
    **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)](/deployment/hosted-inference-testing)**.
  </Accordion>
</AccordionGroup>

***

## Prerequisites

<Steps>
  <Step title="Repo & Python">
    Clone [Bumblebee](https://github.com/Bumblebee-AGI/bumblebee), install deps (e.g. `uv sync` or `pip install -e .`). **Python 3.11+** required.

    For the gateway: `pip install 'bumblebee[gateway]'`.
  </Step>

  <Step title="Ollama & models">
    Install [Ollama](https://ollama.com) and pull models matching your harness config (e.g. `gemma4:26b`, `nomic-embed-text`). See [Hardware](/reference/hardware) for VRAM guidance.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Railway (hybrid)">
    Install the [Railway CLI](https://docs.railway.com/guides/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**.
  </Step>
</Steps>

***

## Choose your path

<Tabs>
  <Tab title="Full hybrid (recommended)">
    From the repo root:

    ```bash theme={null}
    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:

    ```bash theme={null}
    bumblebee setup --profile hybrid
    ```
  </Tab>

  <Tab title="Gateway only">
    If you only need the **home inference stack** (tunnel + token + `.env`) without Railway:

    ```bash theme={null}
    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](/deployment/gateway).
  </Tab>

  <Tab title="Local-only">
    Single machine, no tunnel:

    ```bash theme={null}
    bumblebee setup --profile local
    ```

    Configures local inference and optional bot tokens. For day-to-day local use, [Quickstart](/quickstart) may be enough.
  </Tab>
</Tabs>

***

## What happens inside `bumblebee setup` (hybrid)

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="`.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.
  </Step>

  <Step title="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)](/deployment/hosted-inference-testing).
  </Step>

  <Step title="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](/deployment/gateway)).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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                  |

<Warning>
  **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.
</Warning>

***

## 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](/reference/cli).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tunnel health fails but local health works" icon="link">
    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.
  </Accordion>

  <Accordion title="Railway worker cannot reach inference" icon="train">
    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`.
  </Accordion>

  <Accordion title="Preflight shows Railway not linked" icon="link-slash">
    Run `railway link` from the **repository root** (same folder as `railway.json`). Pick the project that contains `bumblebee-worker` and `bumblebee-api`.
  </Accordion>

  <Accordion title="gateway on does not match tunnel name" icon="link">
    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.
  </Accordion>
</AccordionGroup>

***

## Related docs

<CardGroup cols={2}>
  <Card title="Hybrid Railway overview" icon="cloud" href="/deployment/hybrid-railway">
    Architecture, execution mode, and manual env var reference.
  </Card>

  <Card title="Inference gateway" icon="shield-halved" href="/deployment/gateway">
    Gateway env vars, `gateway on/off/status`, and security notes.
  </Card>

  <Card title="Persistence on Railway" icon="database" href="/deployment/persistence">
    Volumes, workspace dir, and durable files across redeploys.
  </Card>

  <Card title="Environment variables" icon="list" href="/reference/environment-variables">
    Full `.env` and Railway variable reference.
  </Card>
</CardGroup>