mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-09-12 23:02:41 +00:00
e8f0aceee8
## Summary
Separates Fabro server secrets into two explicit scopes: **bootstrap**
secrets that come from process env or `server.env`, and **optional
integration** secrets that come exclusively from the vault. This makes
secret resolution simple and predictable, and removes all `process env →
server.env` fallback paths for optional integrations such as GitHub App,
Slack, Daytona, Brave Search, and LLM provider keys.
## What changed
**New `ToolSecrets` struct in `fabro-agent`** — Brave Search API key is
now passed explicitly through `SessionOptions.tool_secrets` rather than
read from process env inside the tool. The standalone CLI reads the key
at the CLI boundary (with an explicit
`#[expect(clippy::disallowed_methods)]` annotation); the server will
read it from the vault. The error message changes from
`"BRAVE_SEARCH_API_KEY environment variable is not set"` to
`"BRAVE_SEARCH_API_KEY is not configured"`.
**`VaultCredentialSource::vault_only` constructor in `fabro-auth`** —
Adds a constructor that passes `|_| None` as the env lookup, ensuring
the server LLM credential source never resolves provider keys from
process env.
**GitHub App secrets move to vault in install flows** — Both the CLI
`fabro install github` path and the browser install finish handler now
write `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_SECRET`, and
`GITHUB_APP_WEBHOOK_SECRET` to the vault instead of `server.env`.
Switching strategies removes stale secrets from the other strategy's
storage location. The `vault_set` field type changes from `Vec<(String,
String)>` to `Vec<VaultSecretWrite>` to carry per-secret type metadata
(file vs. token).
**`fabro-vault` gains a `fabro-static` dependency** — Needed so the
vault crate can reference canonical env-var names from the shared
registry without a cycle.
**`GH_TOKEN` fallback removed** — `GITHUB_TOKEN` is now read from the
vault only; the changelog and `server-configuration.mdx` note drops
mention of `GH_TOKEN` as an accepted fallback.
**Version bump** — Workspace crates promoted from `0.244.0-nightly.0` to
`0.244.0`.
**Docs** — Internal strategy doc, public admin docs (Docker, Railway,
server-configuration, security, troubleshooting), and integration docs
(GitHub, Slack, Daytona, Brave Search, LiteLLM, tools reference, models)
all updated to reflect vault-only optional secrets and direct users to
`fabro secret set` rather than process env or `server.env`.
### Plan Summary
- **Task 1** (secret registry) — not yet present in this diff;
classification lives in the places that consume it.
- **Task 3–6** (vault-only lookups for GitHub, Slack, Daytona, LLM) —
implemented via `vault_only` constructor, `tool_secrets` threading, and
install-path changes.
- **Task 7** (Brave Search explicit injection) — `ToolSecrets`,
`register_core_tools` wiring, CLI boundary read.
- **Task 8** (install persistence) — GitHub App secrets written to
vault; token strategy writes `GITHUB_TOKEN` to vault and clears app
vault keys; app strategy clears `GITHUB_TOKEN` vault key.
- **Task 9** (docs) — all public and internal docs updated.
### Fabro Details
<details>
<summary>Ran 0 stages in 155m 26s for $60.85</summary>
| Stage | Duration | Cost | Retries |
|---|---|---|---|
| **Total** | **155m 26s** | **$60.85** | **0** |
</details>
<details>
<summary>Ran <code>ImplementPlan.fabro</code> (11 nodes and 14
edges)</summary>
```dot
digraph ImplementPlan {
graph [
goal="Implement and simplify",
model_stylesheet="
* { model: claude-opus-4-7; }
"
]
rankdir=LR
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
toolchain [label="Toolchain", shape=parallelogram, script="command -v cargo >/dev/null || { curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && sudo ln -sf $HOME/.cargo/bin/* /usr/local/bin/; }; cargo --version 2>&1", max_retries=0]
preflight_compile [label="Preflight Compile", shape=parallelogram, script="cargo check -q --workspace 2>&1", max_retries=0]
preflight_lint [label="Preflight Lint", shape=parallelogram, script="cargo +nightly-2026-04-14 clippy -q --workspace --all-targets -- -D warnings 2>&1", max_retries=0]
fix_lints [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", max_visits=3]
implement [label="Implement", prompt="Read the plan file referenced in the goal and implement every step. Make all the code changes described in the plan. Use red/green TDD.", model="gpt-55", reasoning_effort="xhigh"]
simplify_opus [label="Simplify (Opus)", prompt="@prompts/simplify.md"]
simplify_gpt [label="Simplify (GPT-55)", prompt="@prompts/simplify.md", model="gpt-55"]
verify [label="Verify", shape=parallelogram, script="git fetch origin main 2>&1 && git merge --no-edit --no-stat origin/main 2>&1 && cargo +nightly-2026-04-14 fmt --all 2>&1 && cargo dev docs refresh 2>&1 && cargo +nightly-2026-04-14 fmt --check --all 2>&1 && { command -v rg >/dev/null 2>&1 || { echo 'rg is required for verify'; exit 127; }; } && ! rg -n 'AuthMode::Disabled|RunAuthMethod|RunSubjectProvenance|\bActorRef\b|\bActorKind\b|AuthenticatedSubject|AuthenticatedService|AuthorizeRunScoped|AuthorizeRunBlob|AuthorizeStageArtifact|AuthorizeCommandLog|auth_method\s*==\s*\"disabled\"' lib/crates apps lib/packages docs/public/api-reference/fabro-api.yaml 2>&1 && cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings 2>&1 && cargo nextest run --workspace --status-level slow --profile ci 2>&1 && cargo dev docs check 2>&1 && bun install --frozen-lockfile 2>&1 && (cd apps/fabro-web && bun run typecheck) 2>&1 && (cd apps/fabro-web && bun run test) 2>&1 && (cd lib/packages/fabro-api-client && bun run typecheck) 2>&1 && cargo dev build -- -p fabro-cli --release 2>&1", goal_gate=true, retry_target="fixup"]
fixup [label="Fixup", prompt="The verify step failed. Read the build output from context and fix all format, clippy, Rust test, docs, TypeScript typecheck/test, and build failures.", max_visits=3]
start -> toolchain
toolchain -> preflight_compile [condition="outcome=succeeded"]
toolchain -> exit
preflight_compile -> preflight_lint [condition="outcome=succeeded"]
preflight_compile -> exit
preflight_lint -> implement [condition="outcome=succeeded"]
preflight_lint -> fix_lints
fix_lints -> preflight_lint
implement -> simplify_opus -> simplify_gpt -> verify
verify -> exit [condition="outcome=succeeded"]
verify -> fixup
fixup -> verify
}
```
</details>
⚒️ Generated with [Fabro](https://fabro.sh)
---------
Co-authored-by: Fabro <noreply@fabro.sh>
Co-authored-by: Bryan Helmkamp <bryan@brynary.com>
145 lines
6.6 KiB
Text
145 lines
6.6 KiB
Text
---
|
|
title: "Self-host with Docker"
|
|
description: "Run the Fabro server as a Docker container with docker compose, ECS, or any cloud container service"
|
|
---
|
|
|
|
<Warning>
|
|
The server interface is in private early access. Contact [bryan@qlty.sh](mailto:bryan@qlty.sh) if you're interested in trying it.
|
|
</Warning>
|
|
|
|
The supported deployment artifact is the official Fabro image at `ghcr.io/fabro-sh/fabro`. Everything else — `docker compose`, ECS, Cloud Run, Kubernetes, Railway — is just running this image somewhere with the right requirements.
|
|
|
|
## Requirements
|
|
|
|
| Requirement | Value |
|
|
|---|---|
|
|
| **Image** | `ghcr.io/fabro-sh/fabro:nightly` (multi-arch; pin a version for production) |
|
|
| **Persistent volume** | Mount at `/storage`. Stores run history, checkpoints, sessions, the dev token, and JWT keys. |
|
|
| **Port** | The container binds to `$PORT` (default `32276`). Expose it. |
|
|
| **LLM provider key** | Add at least one provider key during the install wizard or later with `fabro secret set` / `fabro provider login`. |
|
|
| **Replicas** | One. The server expects exclusive ownership of `/storage`. |
|
|
|
|
## Quickstart with docker compose
|
|
|
|
The repo ships a `docker-compose.yaml` at the root. Clone the repo (or copy the file), create a `.env` for bootstrap settings if needed, and start it:
|
|
|
|
```bash
|
|
git clone https://github.com/fabro-sh/fabro.git
|
|
cd fabro
|
|
cp .env.example .env
|
|
# edit .env for bootstrap values such as SESSION_SECRET or FABRO_DEV_TOKEN if needed
|
|
docker compose up -d
|
|
```
|
|
|
|
The compose file:
|
|
|
|
- Pulls `ghcr.io/fabro-sh/fabro:nightly`
|
|
- Creates a named volume `fabro-storage` mounted at `/storage`
|
|
- Mounts `/var/run/docker.sock` so Fabro can spawn sandbox containers on the host daemon
|
|
- Exposes port `32276`
|
|
- Loads environment from `.env` if present
|
|
|
|
<Warning>
|
|
Mounting `/var/run/docker.sock` gives the container host-root-equivalent access. Only use the bundled compose service in trusted, single-tenant deployments. See [Sandboxing](/administration/sandboxing) for the threat model.
|
|
</Warning>
|
|
|
|
After the container is healthy, finish setup in your browser following the [install wizard](/reference/server-operations#first-run-web-install-wizard).
|
|
|
|
### Adding a reverse proxy with TLS
|
|
|
|
For a production deployment exposed to the internet, layer the `docker-compose.prod.yaml` overlay on top. It adds a [Caddy](https://caddyserver.com) reverse proxy that terminates TLS (auto-provisioning a Let's Encrypt certificate) and forwards to Fabro:
|
|
|
|
```bash
|
|
# In .env
|
|
FABRO_DOMAIN=fabro.example.com
|
|
|
|
# Then bring the stack up
|
|
docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up -d
|
|
```
|
|
|
|
Leave `FABRO_DOMAIN` unset to serve plain HTTP on `localhost`.
|
|
|
|
## Bootstrap environment variables
|
|
|
|
For the web UI you need a session secret unless install mode is generating the initial local configuration:
|
|
|
|
```bash
|
|
SESSION_SECRET=<64-character hex string>
|
|
```
|
|
|
|
Generate one with `openssl rand -hex 32`.
|
|
|
|
`server.env` and container process env are for bootstrap values only:
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `SESSION_SECRET` | Session encryption secret |
|
|
| `FABRO_DEV_TOKEN` | Optional — pre-set the dev token instead of reading the one written to `/storage` on first boot |
|
|
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | Optional static S3 object-store credentials |
|
|
|
|
Do not put optional integration secrets in `.env` for server runtime. Configure LLM provider keys, Slack, Daytona, Brave Search, `GITHUB_TOKEN`, and GitHub App secrets in the vault with `fabro secret set`, `fabro provider login`, or `fabro install`.
|
|
|
|
Optional:
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `FABRO_DOMAIN` | Public hostname when using the Caddy reverse-proxy overlay |
|
|
|
|
See [Server Configuration](/administration/server-configuration) for the full settings reference, and [`.env.example`](https://github.com/fabro-sh/fabro/blob/main/.env.example) for the complete list.
|
|
|
|
## Cloud container services
|
|
|
|
The same image works on any container orchestrator that supports the requirements above. Common patterns:
|
|
|
|
- **AWS ECS / Fargate** — Task definition referencing `ghcr.io/fabro-sh/fabro:nightly`, EFS volume mounted at `/storage`, port `32276` published, environment variables for bootstrap values, and vault-backed optional integration secrets.
|
|
- **Google Cloud Run** — Cloud Run with a backed volume mount at `/storage`. Pin minimum instances to 1; scale-to-zero interrupts running workflows.
|
|
- **Kubernetes** — One-replica `StatefulSet` (not Deployment) with a `PersistentVolumeClaim` mounted at `/storage`. Expose via Service + Ingress.
|
|
|
|
In all cases: single replica, persistent `/storage`, expose `$PORT`, and configure optional integration secrets in the vault.
|
|
|
|
## Pinning a version
|
|
|
|
`docker-compose.yaml` uses `:nightly` by default, so `docker compose pull && docker compose up -d` picks up the latest nightly. To pin a specific version, change the `image:` line to `ghcr.io/fabro-sh/fabro:<version>`.
|
|
|
|
Release artifacts ship with [SLSA Build Provenance](/reference/verifying-releases) attestations you can verify with `gh attestation verify`.
|
|
|
|
## Pointing the CLI at your server
|
|
|
|
Once the container is running, install the CLI on your local machine and point it at the server:
|
|
|
|
```toml title="~/.fabro/settings.toml"
|
|
[cli.target]
|
|
type = "http"
|
|
url = "https://fabro.example.com/api/v1"
|
|
```
|
|
|
|
For dev-token auth, save the token in the CLI auth store:
|
|
|
|
```bash
|
|
fabro auth login --server https://fabro.example.com/api/v1 --dev-token fabro_dev_...
|
|
```
|
|
|
|
See [Server Operations](/reference/server-operations#pointing-the-cli-at-a-server) for the full CLI-target options.
|
|
|
|
## Caveats
|
|
|
|
- **Volume is load-bearing.** Without a persistent volume at `/storage`, redeploys silently wipe all state — including the dev token and JWT signing keys.
|
|
- **Single replica.** The server expects exclusive ownership of `/storage`. Don't scale to multiple replicas.
|
|
- **Architecture.** The `:nightly` tag is multi-arch. The amd64 variant is the most heavily tested.
|
|
|
|
## Next steps
|
|
|
|
<Columns cols={2}>
|
|
<Card title="Server Operations" icon="server" href="/reference/server-operations">
|
|
Install wizard, web UI, authentication, demo mode, and pointing the CLI at the server.
|
|
</Card>
|
|
<Card title="Server Configuration" icon="gear" href="/administration/server-configuration">
|
|
Full settings.toml reference — auth, reverse-proxy TLS, run defaults, and more.
|
|
</Card>
|
|
<Card title="Deploy to Railway" icon="train" href="/administration/deploy-railway">
|
|
One-click managed shortcut for the same Docker image.
|
|
</Card>
|
|
<Card title="Sandboxing" icon="shield" href="/administration/sandboxing">
|
|
The Docker sandbox provider's security model and trust assumptions.
|
|
</Card>
|
|
</Columns>
|