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

# Self-hosting overview

> What runs when you host Bellows yourself, how a task moves through it, and what you need before you start.

Bellows is open source. You can run the whole platform on your own machine or cluster instead of using [bellows.cloud](https://bellows.cloud). The product works the same way: a task runs an agent in a sandboxed runner, the [gates](https://docs.bellows.cloud/guides/gates.md) check the result, and a pull request is published.

## Components

| Component | What it does | Required |
| - | - | - |
| **Web app and board (server)** | One Node process (`server/`). Serves the web app and its API, the [MCP endpoint](https://docs.bellows.cloud/mcp/tools.md) when enabled, and the job board. Keeps tasks, members, settings and telemetry in Postgres. | Yes |
| **Driver** | Polls the board for queued tasks, claims them with a lease, and starts one runner per task. It is the only process that starts containers or pods. | Yes |
| **Runners** | A container (Docker) or a Job pod (Kubernetes) per task. The agent works on a copy of your repository on a task volume. | Yes |
| **Executor images** | The images a runner starts from: `claude-executor` for Claude Code and `opencode-executor` for OpenCode. You build or pull them yourself. | Yes |
| **PostgreSQL** | The only database. Holds everything the board knows. | Yes |
| **GitHub App** | Lets Bellows read repositories, list them, and mint short-lived tokens for runners. It also defines your organizations: one installation is one organization. | Yes |
| **GitHub OAuth App** | Signs members in when `AUTH_MODE=github`. A separate registration from the GitHub App. | For sign-in |
| **Secret store** | Holds environment secrets and connection credentials. Backend is `database`, `aws`, `vault` or `gcp`. | Yes |
| **Object store** | Holds task artifacts and uploaded attachments. S3-compatible, or a local directory on a single replica. | Yes (defaults to the filesystem) |
| **Telemetry collector** | An OpenTelemetry collector. Receives metrics from runners and forwards them to the board. | Recommended |
| **Jira app** | An Atlassian OAuth app that powers **Connect Jira**. | Optional |

## How a task flows

**1. You create a task**

From the web app, the CLI, the MCP server or the API. The board stores it as a queued job in Postgres.

**2. The driver claims it**

The driver polls the board (every 5 seconds by default) and takes a lease on the job. The claim carries the repository, the executor, your environment variables and the plan read from `.bellows.yaml`.

**3. A runner starts**

The driver creates a task volume, starts a runner from the executor image, and clones the repository with a token the board minted from the GitHub App.

**4. The agent works**

The runner reports progress and questions to the board. Its telemetry goes to the collector, which forwards it to the board.

**5. Gates run**

The driver runs the gates declared in `.bellows.yaml`, plus any [services](https://docs.bellows.cloud/guides/services.md) the repository declares.

**6. A PR is published**

The board publishes the pull request through the GitHub App and keeps following it. Logs, artifacts and the verdict stay on the task.

```mermaid theme={null}
flowchart LR
  user[Member: web, CLI, MCP, API] --> board[Board and web app]
  board <--> pg[(PostgreSQL)]
  board --> store[(Object store)]
  board <--> secrets[(Secret store)]
  driver[Driver] -- "claim, lease, verdict" --> board
  driver -- "docker run / Kubernetes Job" --> runner[Runner: executor image]
  runner -- "clone, push" --> gh[GitHub]
  board -- "App token, PRs" --> gh
  runner -- "OTLP metrics" --> col[Collector]
  col --> board
```

> [!NOTE]
>
> The board never starts containers. If the driver is down, queued tasks wait until a driver claims them. A driver that is stopped cleanly hands its running tasks back to the board (see `DRIVER_HANDOVER_MS`).

## What you need

| Need | Details |
| - | - |
| **PostgreSQL** | PostgreSQL 17 is what the Compose file and the local Helm state chart run. No extensions are needed, so a managed Postgres works. |
| **Docker or Kubernetes** | Docker (with Compose) on one machine for a trial. A Kubernetes cluster with the Helm chart for a team. The driver is told which with `EXECUTOR=docker` or `EXECUTOR=kubernetes`. |
| **A GitHub App** | Id and private key are required. The board refuses to start without them. See [GitHub App](https://docs.bellows.cloud/self-host/github-app.md). |
| **A GitHub OAuth App** | For member sign-in. See [GitHub App](https://docs.bellows.cloud/self-host/github-app.md). |
| **A model credential** | For example `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` for Claude Code, passed to runners by the driver. |
| **A domain and TLS** | Needed for any shared deployment. Set `PUBLIC_URL` to the public https origin and `COOKIE_SECURE=1`. MCP needs an https `PUBLIC_URL`. A local trial can use `http://127.0.0.1`. |
| **Node.js 22 or newer** | Only to run `npm run secrets:init` and the CLI from a clone. |

> [!WARNING]
>
> The Docker executor mounts the Docker socket into the driver. That is root on the host. Read [Security](https://docs.bellows.cloud/self-host/security.md) before running it anywhere shared.

## Where to go next

> [card] [Docker Compose](https://docs.bellows.cloud/self-host/docker-compose.md)
>
> Run Bellows on one machine with the Docker executor.

> [card] [Kubernetes](https://docs.bellows.cloud/self-host/kubernetes.md)
>
> Deploy with the Helm chart. Each task is a pod.

> [card] [GitHub App](https://docs.bellows.cloud/self-host/github-app.md)
>
> Register the App and the OAuth App.

> [card] [Jira app](https://docs.bellows.cloud/self-host/jira-app.md)
>
> Turn on Connect Jira with an Atlassian OAuth app.

> [card] [Configuration](https://docs.bellows.cloud/self-host/configuration.md)
>
> Every server and driver environment variable.

> [card] [Security](https://docs.bellows.cloud/self-host/security.md)
>
> What each credential grants and where the boundaries are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.