From 19d32c7b874f988d2dbcb4453becf6c1e99b6619 Mon Sep 17 00:00:00 2001 From: Kyle Dodson Date: Thu, 1 Oct 2026 19:52:41 -0700 Subject: [PATCH] Fix docs related to Local runs --- docs/public/core-concepts/workflows.mdx | 2 +- docs/public/execution/environments.mdx | 13 +++++++------ docs/public/execution/run-configuration.mdx | 12 ++++++------ 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/public/core-concepts/workflows.mdx b/docs/public/core-concepts/workflows.mdx index af2866ed2..23b051139 100644 --- a/docs/public/core-concepts/workflows.mdx +++ b/docs/public/core-concepts/workflows.mdx @@ -203,7 +203,7 @@ Target selection depends on the environment: | Selection | Local environment | Clone-based environment (Docker, Daytona, or plugin) | | --- | --- | --- | -| Default cwd or `--target-from PATH` | Uses the live directory, including uncommitted files | Uses the enclosing Git repository and exact available commit; a non-Git directory selects an empty workspace | +| Default cwd or `--target-from PATH` | Clones the enclosing Git repository's committed `HEAD`; uncommitted files are not included, and a non-Git directory selects an empty workspace | Uses the enclosing Git repository and exact available commit; a non-Git directory selects an empty workspace | | `--target-repo OWNER/REPO` or `--target OWNER/REPO[@BRANCH]` | Rejected | Uses the selected repository and exact observed branch commit; cloning must be enabled | For clone-based execution, a target path selects a repository, not a subdirectory diff --git a/docs/public/execution/environments.mdx b/docs/public/execution/environments.mdx index 1bdd9fede..0511410d3 100644 --- a/docs/public/execution/environments.mdx +++ b/docs/public/execution/environments.mdx @@ -227,20 +227,21 @@ Install seeds a `default` environment into SQLite. It is a normal persisted envi ## Local -`local` runs tools directly in the resolved working directory. It offers no filesystem or network isolation, so use it only for trusted workflows. +`local` runs tools on the Fabro host, in a workspace under the run's directory. It offers no filesystem or network isolation, so use it only for trusted workflows. Create a server-managed local-provider environment through the environments API when you need a host `cwd`. A version-backed run intent can submit -`{ "kind": "folder", "path": "/absolute/server/path" }` to run in an existing +`{ "kind": "folder", "path": "/absolute/server/path" }` to start from an existing server directory. Fabro accepts this target only with a Local environment, resolves symlinks and `..`, requires an existing directory, and persists the canonical UTF-8 path. The target path takes precedence over the environment's -`cwd`. Because the run executes in place with the Local provider's unrestricted +`cwd`. Because the Local provider has unrestricted host access, use folder targets only in trusted single-tenant deployments. -Docker and Daytona always reject folder targets. This does not add Local Git -cloning or Local scratch workspaces for the `none` target. Local folder runs -execute in place without Fabro Git checkpoints: retries retain the canonical +Docker and Daytona always reject folder targets. Local environments do not +support the `none` target. Local folder runs +work in a clone of the folder's committed `HEAD` (see +[Checkpoints](/execution/checkpoints)): retries retain the canonical folder target, but fork and rewind are unavailable for these runs. When `cwd` is set, local runs execute commands from that absolute server-side diff --git a/docs/public/execution/run-configuration.mdx b/docs/public/execution/run-configuration.mdx index 7213dc229..b4bc7b4f5 100644 --- a/docs/public/execution/run-configuration.mdx +++ b/docs/public/execution/run-configuration.mdx @@ -233,7 +233,7 @@ Fabro substitutes `{{ vars.* }}` when the server creates the run, then resolves ### `[run.clone]` -Configure whether clone-based sandboxes clone the run's GitHub origin before execution. +Configure whether the run's repository is cloned into its workspace before execution: the GitHub origin for Docker and Daytona, or the target folder's repository for Local. ```toml title="run.toml" [run.clone] @@ -241,12 +241,12 @@ enabled = true depth = 100 ``` -Set `enabled = false` to start Docker and Daytona runs with an empty provider workspace. Use [prepare steps](#runprepare) to clone or create any files the workflow needs. +Set `enabled = false` to start runs with an empty workspace. Use [prepare steps](#runprepare) to clone or create any files the workflow needs. | Field | Description | |---|---| | `enabled` | When `false`, Fabro skips the repository clone. Defaults to `true`. | -| `depth` | Git history depth for Docker and Daytona. Defaults to `100`. Set it to `0` to clone full history. | +| `depth` | Git history depth. Defaults to `100`. Set it to `0` to clone full history. | ### `[run.run_branch]` @@ -318,9 +318,9 @@ memory = "8GB" | `labels` | Provider labels. Merge by key across layers. | | `env` | Environment variables passed to command and agent execution. Merge by key across layers. | -When `provider = "local"`, Fabro runs directly in the resolved working -directory. If you want local isolation, create or enter a separate clone or Git -worktree yourself. +When `provider = "local"`, Fabro works in a clone of the target folder's +committed `HEAD`, not in the folder itself, so uncommitted changes are not +included. Environment variable values can combine literal text with server variables and token secrets: