mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-09-20 00:11:34 +00:00
c81fcc2a27
## Summary
On startup, Fabro now detects confidently migratable pre-v1.0
`[run.sandbox]` config files and rewrites them in-place to the
`[run.environment]` + `[environments.default]` named-environment syntax.
The original file is preserved as a sibling
`*.legacy-sandbox-migration.bak` before any write. Unsupported or
ambiguous keys produce a targeted error listing exact key paths rather
than a generic TOML unknown-field failure.
### Plan Summary
- **New module** `legacy_sandbox_migration.rs` owns all detection,
rewriting, backup logic, and unsupported-key diagnostics — isolated so
it can be deleted before v1.0.
- **`load.rs` hook** catches parse failures on file loads and attempts
migration before re-raising the original error, leaving in-memory
`SettingsLayer` parsing strict and unchanged.
- **Field mappings** cover Daytona (snapshot, volumes, labels,
lifecycle, `auto_stop_interval`) and Docker (image, `memory_limit`,
`cpu_quota` divisible by 100 000, `skip_clone`).
- **Ambiguity guard** rejects files that already contain
`[run.environment]` or `[environments.default]` alongside
`[run.sandbox]`.
- **Docs** add a `<Warning>` block to `environments.mdx` and a new
`2026-05-23.mdx` changelog entry.
This PR also bundles two unrelated improvements that landed in the same
branch: additional sort keys (`repo`, `title`, `workflow`, `changes`)
for the runs list API and UI, and a test isolation fix in `user.rs` that
wraps path assertions in `with_var` to avoid `FABRO_HOME` leakage.
### Migration flow
```mermaid
flowchart TB
A[load_settings_path] --> B{parse SettingsLayer}
B -- ok --> G[resolve paths / return]
B -- err --> C{migrate_settings_path}
C -- no legacy sandbox --> D[return original parse error]
C -- has new env config --> E[error: ambiguous, manual fix required]
C -- unsupported keys --> F[error: list unsupported keys]
C -- success --> H[write .bak, rewrite file, warn]
H --> I[parse migrated SettingsLayer]
I --> G
```
### Fabro Details
<details>
<summary>Ran 0 stages in 53m 26s for $16.82</summary>
| Stage | Duration | Cost | Retries |
|---|---|---|---|
| **Total** | **53m 26s** | **$16.82** | **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 && ! 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: Fabro <fabro@fabro.sh>
Co-authored-by: Bryan Helmkamp <bryan@brynary.com>
203 lines
5.8 KiB
Text
203 lines
5.8 KiB
Text
---
|
|
title: "Environments"
|
|
description: "Reusable named execution environments for workflow runs"
|
|
---
|
|
|
|
Fabro separates **environments** from **sandboxes**:
|
|
|
|
- An **environment** is reusable desired configuration: provider, image, resources, network, lifecycle, labels, volumes, and environment variables.
|
|
- A **sandbox** is the concrete runtime instance Fabro creates for a run from the selected environment.
|
|
|
|
<Warning>
|
|
Older pre-v1.0 config files that still use `[run.sandbox]` are temporarily auto-migrated when Fabro loads them from disk. Fabro writes a sibling `*.legacy-sandbox-migration.bak` file, rewrites the config to `[run.environment]` plus `[environments.default]`, and then continues startup.
|
|
|
|
This compatibility rewrite only handles direct field mappings. Unsupported legacy fields fail with a migration message that lists the keys to edit manually. The rewrite path will be removed before v1.0.
|
|
</Warning>
|
|
|
|
Runs select environments by slug:
|
|
|
|
```toml title="workflow.toml"
|
|
[run.environment]
|
|
id = "fabro-dev"
|
|
```
|
|
|
|
Environment catalogs can live in `settings.toml`, `.fabro/project.toml`, or `workflow.toml`, and merge through the normal settings precedence. The built-in default is `default`, a Docker environment using `buildpack-deps:noble`.
|
|
|
|
## Defining environments
|
|
|
|
```toml title="workflow.toml"
|
|
[run.environment]
|
|
id = "fabro-dev"
|
|
|
|
[environments.fabro-dev]
|
|
provider = "daytona" # local | docker | daytona
|
|
|
|
[environments.fabro-dev.image]
|
|
ref = "fabro-v11" # Docker image or Daytona snapshot name
|
|
dockerfile = { path = "Dockerfile" }
|
|
|
|
[environments.fabro-dev.resources]
|
|
cpu = 8
|
|
memory = "16GB"
|
|
disk = "20GB"
|
|
|
|
[environments.fabro-dev.network]
|
|
mode = "cidr_allow_list" # allow_all | block | cidr_allow_list
|
|
allow = ["10.0.0.0/8"]
|
|
|
|
[environments.fabro-dev.lifecycle]
|
|
preserve = false
|
|
stop_on_terminal = true
|
|
auto_stop = "30m"
|
|
|
|
[environments.fabro-dev.labels]
|
|
repo = "fabro-sh/fabro"
|
|
|
|
[[environments.fabro-dev.volumes]]
|
|
id = "vol-agent-state"
|
|
mount_path = "/home/daytona/agent-state"
|
|
subpath = "auth"
|
|
|
|
[environments.fabro-dev.env]
|
|
NODE_ENV = "development"
|
|
```
|
|
|
|
Run-level overrides are sparse and apply only to the selected environment:
|
|
|
|
```toml title="workflow.toml"
|
|
[run.environment]
|
|
id = "fabro-dev"
|
|
|
|
[run.environment.resources]
|
|
memory = "32GB"
|
|
|
|
[run.environment.lifecycle]
|
|
preserve = true
|
|
```
|
|
|
|
`env` and `labels` merge by key. `volumes` replace as a whole list when set at a higher-precedence layer.
|
|
|
|
## Selecting an environment from the CLI
|
|
|
|
Use `--environment` with an environment slug:
|
|
|
|
```bash
|
|
fabro run workflow.fabro --environment fabro-dev
|
|
fabro preflight workflow.fabro --environment ci
|
|
fabro server start --environment default
|
|
```
|
|
|
|
`--preserve-sandbox` still controls the concrete runtime instance lifecycle for a run. Runtime commands such as `fabro sandbox ssh` keep the word "sandbox" because they operate on an already-created runtime instance.
|
|
|
|
## Built-in default
|
|
|
|
```toml
|
|
[run.environment]
|
|
id = "default"
|
|
|
|
[environments.default]
|
|
provider = "docker"
|
|
|
|
[environments.default.image]
|
|
ref = "buildpack-deps:noble"
|
|
|
|
[environments.default.resources]
|
|
cpu = 2
|
|
memory = "4GB"
|
|
|
|
[environments.default.lifecycle]
|
|
preserve = false
|
|
stop_on_terminal = true
|
|
```
|
|
|
|
## Provider mappings
|
|
|
|
| Environment field | Local | Docker | Daytona |
|
|
|---|---|---|---|
|
|
| `image.ref` | Ignored | Docker image | Snapshot name |
|
|
| `image.dockerfile` | Ignored | Warning; ignored | Snapshot Dockerfile; requires `image.ref` |
|
|
| `resources.cpu` | Warning; ignored | `cpu_quota = cpu * 100000` | Snapshot CPU |
|
|
| `resources.memory` | Warning; ignored | Container memory limit | Snapshot memory |
|
|
| `resources.disk` | Warning; ignored | Warning; ignored | Snapshot disk |
|
|
| `network.mode = "allow_all"` | Host network | Docker default bridge | Daytona allow-all |
|
|
| `network.mode = "block"` | Error | Docker `none` network | Daytona block |
|
|
| `network.mode = "cidr_allow_list"` | Error | Error | Daytona CIDR allow-list |
|
|
| `labels` | Warning; ignored | Warning; ignored | Daytona labels |
|
|
| `volumes` | Warning; ignored | Warning; ignored | Daytona volume mounts |
|
|
| `lifecycle.auto_stop` | Warning; ignored | Warning; ignored | Daytona auto-stop |
|
|
| `env` | Process environment overlay | Container environment | Sandbox environment |
|
|
|
|
## Local
|
|
|
|
`local` runs tools directly in the resolved working directory. It offers no filesystem or network isolation, so use it only for trusted workflows.
|
|
|
|
```toml
|
|
[run.environment]
|
|
id = "host"
|
|
|
|
[environments.host]
|
|
provider = "local"
|
|
```
|
|
|
|
Fabro hard-errors if a local environment asks for blocked or CIDR-restricted networking because the provider cannot enforce it.
|
|
|
|
## Docker
|
|
|
|
Docker runs tools inside a container created from `image.ref`. Docker is the built-in default provider.
|
|
|
|
```toml
|
|
[run.environment]
|
|
id = "ci"
|
|
|
|
[environments.ci]
|
|
provider = "docker"
|
|
|
|
[environments.ci.image]
|
|
ref = "buildpack-deps:noble"
|
|
|
|
[environments.ci.resources]
|
|
cpu = 2
|
|
memory = "4GB"
|
|
|
|
[environments.ci.network]
|
|
mode = "block"
|
|
```
|
|
|
|
Docker and Daytona are clone-based providers. When a run has a GitHub origin, Fabro clones it into the provider workspace. Set `[run.clone] enabled = false` to start with an empty workspace.
|
|
|
|
## Daytona
|
|
|
|
Daytona runs tools in a cloud sandbox. `image.ref` is the snapshot name. If `image.dockerfile` is set and the snapshot does not exist, Fabro creates the snapshot; `image.ref` is required so the snapshot has a name.
|
|
|
|
```toml
|
|
[run.environment]
|
|
id = "cloud"
|
|
|
|
[environments.cloud]
|
|
provider = "daytona"
|
|
|
|
[environments.cloud.image]
|
|
ref = "rust-dev"
|
|
dockerfile = { path = "Dockerfile" }
|
|
|
|
[environments.cloud.resources]
|
|
cpu = 4
|
|
memory = "8GB"
|
|
disk = "20GB"
|
|
|
|
[environments.cloud.lifecycle]
|
|
auto_stop = "30m"
|
|
|
|
[environments.cloud.network]
|
|
mode = "cidr_allow_list"
|
|
allow = ["208.80.154.232/32", "10.0.0.0/8"]
|
|
```
|
|
|
|
Daytona volumes reference existing provider-managed volumes:
|
|
|
|
```toml
|
|
[[environments.cloud.volumes]]
|
|
id = "vol-agent-state"
|
|
mount_path = "/home/daytona/agent-state"
|
|
subpath = "agent-auth"
|
|
```
|