### Quickstart with Docker Compose

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/administration/self-host-docker.mdx

Clone the Fabro repository, copy the example environment file, and start the Docker Compose stack to quickly set up a local Fabro instance.

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

--------------------------------

### Start Fabro Server for Installation Wizard

Source: https://github.com/fabro-sh/fabro/blob/main/apps/marketing/public/install.md

Starts the Fabro server in the foreground. It will detect unconfigured status and enter install mode, printing a URL for the web wizard.

```bash
fabro server start
```

--------------------------------

### Setup Started Event

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/events.md

Emitted when the setup process begins. Includes the total number of setup commands to be executed.

```json
{
  "id": "...", "ts": "...", "run_id": "...",
  "event": "setup.started",
  "properties": {
    "command_count": 3
  }
}
```

--------------------------------

### Setup Command Started Event

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/events.md

Emitted when an individual setup command starts. Includes the command string and its index.

```json
{
  "id": "...", "ts": "...", "run_id": "...",
  "event": "setup.command.started",
  "properties": {
    "command": "npm install",
    "index": 0
  }
}
```

--------------------------------

### Start the server

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/server-operations.mdx

Starts the Fabro server. If configuration files do not exist, it enters an install mode to guide the user through initial setup via a web wizard. Common flags can be used to customize the bind address, model, environment, and concurrency limits.

```APIDOC
## `fabro server start`

### Description
Starts the Fabro server. If `~/.fabro/settings.toml` does not exist, it enters an install mode to guide the user through initial setup via a web wizard. Common flags can be used to customize the bind address, model, environment, and concurrency limits.

### Command
```bash
fabro server start
```

### Flags

| Flag | Default | Description |
|---|---|---|
| `--bind` | `~/.fabro/fabro.sock` | Address to bind: `IP` or `IP:port` for TCP, or a path for Unix socket |
| `--model` | — | Override default LLM model |
| `--environment` | — | Override default environment slug |
| `--max-concurrent-runs` | `5` | Maximum concurrent run executions |
```

--------------------------------

### Quick Start: Initialize Client and Generate Text

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/sdk.mdx

Demonstrates the basic setup for using the Fabro SDK, including initializing a client from environment variables and making a text generation call.

```rust
use fabro_auth::EnvCredentialSource;
use fabro_llm::client::Client;
use fabro_llm::generate::{generate, GenerateParams};
use fabro_llm::model::catalog::LlmCatalogSettings;
use fabro_llm::model::Catalog;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = EnvCredentialSource::new();
    let catalog = Arc::new(Catalog::from_builtin_with_overrides(&LlmCatalogSettings::default())?);
    let client = Client::from_source(&source, Arc::clone(&catalog)).await?;

    let result = generate(
        GenerateParams::new("claude-sonnet-4-5", client.clone())
            .prompt("Explain ownership in Rust in two sentences.")
    ).await?;

    println!("{}", result.text());
    println!("Tokens used: {}", result.total_usage.total_tokens);
    Ok(())
}
```

--------------------------------

### Setup Project Environment

Source: https://github.com/fabro-sh/fabro/blob/main/evals/swe-bench/README.md

Installs project dependencies using pip within a virtual environment. Ensure you are in the 'evals/swe-bench' directory.

```bash
cd evals/swe-bench
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Quick Start: Initialize and Run an AI Agent Session

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/sdk.mdx

This example demonstrates initializing an AI agent session with specified LLM, sandbox, and profile, then processing user input. Ensure you subscribe to events before sending input.

```rust
use fabro_agent::{
    AnthropicProfile, LocalSandbox, Session, SessionOptions,
};
use fabro_auth::EnvCredentialSource;
use fabro_llm::client::Client;
use fabro_model::catalog::LlmCatalogSettings;
use fabro_model::Catalog;
use std::path::PathBuf;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = EnvCredentialSource::new();
    let catalog = Arc::new(Catalog::from_builtin_with_overrides(&LlmCatalogSettings::default())?);
    let client = Client::from_source(&source, Arc::clone(&catalog)).await?;
    let sandbox = Arc::new(LocalSandbox::new(PathBuf::from(".")));
    let profile = Arc::new(AnthropicProfile::new("claude-sonnet-4-5"));
    let config = SessionOptions::default();

    let mut session = Session::new(client, profile, sandbox, config);
    session.initialize().await?;

    // Subscribe to events before sending input
    let mut events = session.subscribe();
    tokio::spawn(async move {
        while let Ok(event) = events.recv().await {
            if let fabro_agent::AgentEvent::TextDelta { delta } = &event.event {
                print!("{delta}");
            }
        }
    });

    session.process_input("List the files in this directory").await?;
    session.close();
    Ok(())
}
```

--------------------------------

### Install Fabro Environment

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/cli.mdx

Use the `fabro install` command to set up the Fabro environment, including LLMs, certificates, and GitHub integration. This command can also accept sub-commands for specific setup tasks.

```bash
fabro install [OPTIONS] [COMMAND]
```

--------------------------------

### Develop Fabro Web Frontend

Source: https://github.com/fabro-sh/fabro/blob/main/CONTRIBUTING.md

Install dependencies, start the development server, run tests, and perform type checking for the web frontend. Navigate to the correct directory first.

```bash
cd apps/fabro-web
bun install
bun run dev        # start dev server
bun test           # run tests
bun run typecheck  # type check
```

--------------------------------

### Update Public SDK Example for Initialization

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-05-03-fix-agent-stage-cancellation-plan.md

This example demonstrates how to call the `initialize()` method in public SDK documentation.

```rust
initialize().await?
```

--------------------------------

### Prepare Steps for Workflow Execution

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/execution/run-configuration.mdx

Define shell commands to run before the workflow starts, such as installing dependencies. Each step must exit with status 0.

```toml
[[run.prepare.steps]]
script = "pip install -r requirements.txt"

[[run.prepare.steps]]
script = "npm install"
```

--------------------------------

### Install Fabro CLI-only

Source: https://github.com/fabro-sh/fabro/blob/main/README.md

Runs the setup wizard for Fabro in a CLI-only mode, suitable for headless or scripted environments.

```bash
fabro install
```

--------------------------------

### Run Started Event Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/events.md

Emitted when the workflow run begins. Contains information about the workflow name, branches, and the run's goal.

```json
{
  "id": "...", "ts": "...", "run_id": "...",
  "event": "run.started",
  "properties": {
    "name": "my-workflow",
    "base_branch": "main",
    "base_sha": "abc123...",
    "run_branch": "fabro/run-01JQXYZ",
    "worktree_dir": "/tmp/fabro-worktrees/",
    "goal": "Fix the login bug"
  }
}
```

--------------------------------

### Setup Completed Event

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/events.md

Emitted when the entire setup process completes successfully. Includes the total duration of the setup.

```json
{
  "id": "...", "ts": "...", "run_id": "...",
  "event": "setup.completed",
  "properties": {
    "duration_ms": 15000
  }
}
```

--------------------------------

### Start Split Web Stack

Source: https://github.com/fabro-sh/fabro/blob/main/docker/split-web/README.md

Starts the Docker Compose stack defined in docker-compose.split-web.yaml.

```sh
docker compose -f docker-compose.split-web.yaml up
```

--------------------------------

### Step 1: Initial Server Resolution Setup

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md

Add `CommandContext`, `ServerMode`, `ctx.server()` caching, convert storage-dir-backed connect path to `ServerStoreClient`, add `ServerSummaryLookup::from_client(...)`, and thread preloaded settings into server resolution.

```rust
add `CommandContext`, `ServerMode`, `ctx.server()` caching semantics, convert the storage-dir-backed connect path to construct `ServerStoreClient`, add `ServerSummaryLookup::from_client(...)`, and thread preloaded `machine_settings` / `base_config_path` into server resolution so migrated commands stop re-loading settings inside connection helpers
```

--------------------------------

### Boot the demo environment

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/updating-web-screenshots.md

Starts the demo environment using Docker Compose. Ensure the server is ready before proceeding.

```bash
docker compose up -d
```

--------------------------------

### GET /api/v1/runs/{id}/pair Response Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-18-server-side-run-pairing-api-events.md

Example response for the GET /api/v1/runs/{id}/pair endpoint, showing an active pair and available targets. This response structure is defined by RunPairStatusResponse.

```json
{
  "run_id": "01HZX6M0P7SE4VJ9Y3X2B8E9QF",
  "current_pair": {
    "pair_id": "01HZX6M29F1CD5YYMHT1F5D7WQ",
    "run_id": "01HZX6M0P7SE4VJ9Y3X2B8E9QF",
    "status": "active",
    "started_at": "2026-05-18T12:00:01Z",
    "ended_at": null,
    "failure_reason": null,
    "target": {
      "stage_id": "code@1",
      "node_id": "code",
      "node_label": "Code",
      "visit": 1,
      "agent_session_id": "ses_01",
      "provider": "openai",
      "model": "gpt-5.3"
    }
  },
  "targets": [
    {
      "stage_id": "review@1",
      "node_id": "review",
      "node_label": "Review",
      "visit": 1,
      "agent_session_id": "ses_02",
      "provider": "openai",
      "model": "gpt-5.3"
    }
  ]
}
```

--------------------------------

### Full Example Configuration

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/user-configuration.mdx

A comprehensive TOML configuration file demonstrating various settings for CLI, LLM providers, and run-time integrations.

```toml
_version = 1

[cli.target]
type = "http"
url = "https://fabro.example.com/api/v1"

[cli.exec]
prevent_idle_sleep = true

[cli.exec.model]
provider = "anthropic"
name = "claude-opus-4-6"

[cli.exec.agent]
permissions = "read-write"

[cli.output]
format = "text"
verbosity = "normal"

[cli.updates]
check = true

[cli.logging]
level = "info"

[llm.providers.proxy]
display_name = "Acme Gateway"
adapter = "openai_compatible"
base_url = "https://llm-gateway.example.com/v1"
aliases = ["gateway"]

[llm.providers.proxy.auth]
credentials = ["env:ACME_GATEWAY_API_KEY", "vault:ACME_GATEWAY_API_KEY"]

[llm.providers.proxy.extra_headers]
x-portkey-api-key = { env = "PORTKEY_API_KEY" }
x-portkey-config = { literal = "@bedrock-prod" }

[llm.models."team-code-large"]
provider = "proxy"
api_id = "provider-wire-model-name"
agent_profile = "anthropic"
display_name = "Team Code Large"
default = true
aliases = ["team-code"]

[llm.models."team-code-large".controls]
reasoning_effort = ["low", "medium", "high"]
speed = ["fast"]

[llm.models."team-code-large".costs]
input_cost_per_mtok = 1.50
output_cost_per_mtok = 8.00

[llm.models."team-code-large".costs.speed.fast]
input_cost_per_mtok = 3.00
output_cost_per_mtok = 16.00

[run.model]
name = "claude-sonnet-4-5"

[run.git.author]
name = "fabro-bot"
email = "fabro-bot@company.com"

[run.pull_request]
enabled = true

[run.integrations.github.permissions]
contents = "write"
pull_requests = "write"

[run.agent.mcps.filesystem]
type = "stdio"
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
startup_timeout = "15s"
tool_timeout = "90s"

[run.agent.mcps.filesystem.env]
NODE_ENV = "production"

[run.agent.mcps.sentry]
type = "http"
url = "https://mcp.sentry.dev/mcp"

[run.agent.mcps.sentry.headers]
Authorization = "Bearer sk-xxx"

```

--------------------------------

### Fabro Server Install Mode Startup Log

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/specs/2026-04-18-web-install-design.md

This message is printed to stderr when the Fabro server starts in install mode. It provides instructions and a URL for the user to access the web-based installation wizard.

```text
  ⚒️  Fabro server is unconfigured — install mode active.

  Open this URL in your browser to finish setup:
    https://fabro.up.railway.app/install?token=8H_K2…

  Or visit the root path for the install token instructions.
```

--------------------------------

### CLI Installer: Usage Text Update

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-14-optional-llm-install.md

Update the non-interactive usage text for the CLI installer to include an example of using the `--skip-llm` flag.

```text
Usage: fabro install --non-interactive [OPTIONS]

Options:
  --skip-llm              Skip LLM configuration.
  --llm-provider <PROVIDER>  Specify LLM provider (e.g., openai, azure-openai).
  --llm-api-key-stdin     Read LLM API key from stdin.
  --llm-api-key-env <ENV>  Read LLM API key from environment variable.
  --github-token <TOKEN>  GitHub token for authentication.
  --config-path <PATH>    Path to the configuration file.
  -h, --help              Print help information
```

--------------------------------

### Set Up Isolated Storage and Load Live Environment Variables

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-17-live-provider-workflow-testing.md

Prepare the testing environment by creating a temporary directory for Fabro storage and sourcing live API keys from a .env.live file. Ensure the .env.live file is not committed to version control.

```bash
export FABRO_STORAGE_DIR="$(mktemp -d)"
set -a && source .env.live && set +a
```

--------------------------------

### Example Setup Failure Event Payload

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-04-30-preserve-exec-failure-diagnostics.md

This JSON structure represents a canonical event payload for a setup failure. It includes command details, exit code, and truncated execution output metadata.

```json
{
  "event": "setup.failed",
  "properties": {
    "command": "example command",
    "index": 0,
    "exit_code": 1,
    "stderr": "existing compatibility field",
    "exec_output_tail": {
      "stdout": "bounded redacted stdout tail",
      "stderr": "bounded redacted stderr tail",
      "stderr_truncated": true
    }
  }
}
```

--------------------------------

### Skip LLM Setup During Fabro Install (CLI)

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/changelog/2026-05-14.mdx

Use this command for non-interactive Fabro installations where LLM credentials are not immediately required. Skipping marks the LLM step as complete without saving provider secrets.

```bash
fabro install --non-interactive --skip-llm --github-strategy token --github-username acme-dev
```

--------------------------------

### Startup Storage Migration Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/internal/migrations-strategy.md

Shows how to run migrations before a runtime component consumes data, specifically for startup storage like vaults. It loads the vault, runs migrations, and returns a report.

```rust
let mut vault = load_startup_vault(vault_path)?;
let report = migrations::run_migrations(&mut vault, server_env_path, &env_entries)?;
```

--------------------------------

### Command Hook Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/agents/hooks.mdx

A simple shell command hook that runs a script before a stage starts. This is the most common hook type.

```toml
[[hooks]]
event = "stage_start"
command = "./scripts/pre-check.sh"

```

--------------------------------

### GET /api/v1/repos/github/{owner}/{name}

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md

Checks if the Fabro server has read-write access to a specified GitHub repository. It returns details about the repository's accessibility, default branch, privacy, and permissions. If the GitHub App is not installed on the repository, it provides an installation URL.

```APIDOC
## GET /api/v1/repos/github/{owner}/{name}

### Description
Checks server access to a GitHub repository.

### Method
GET

### Endpoint
/api/v1/repos/github/{owner}/{name}

### Parameters
#### Path Parameters
- **owner** (string) - Required - GitHub repository owner.
- **name** (string) - Required - GitHub repository name.

### Response
#### Success Response (200)
- **owner** (string) - GitHub repository owner.
- **name** (string) - GitHub repository name.
- **accessible** (boolean) - Whether the server has read-write access to this repository.
- **default_branch** (string) - Optional - Default branch name, if accessible.
- **private** (boolean) - Optional - Whether the repository is private, if accessible.
- **permissions** (object) - Optional - Detected permission levels.
  - **pull** (boolean)
  - **push** (boolean)
  - **admin** (boolean)
- **install_url** (string) - Optional - GitHub App installation URL when the repo is not yet accessible.

#### Response Example
```json
{
  "owner": "acme-corp",
  "name": "my-app",
  "accessible": true,
  "default_branch": "main",
  "private": false,
  "permissions": {
    "pull": true,
    "push": true,
    "admin": false
  },
  "install_url": null
}
```

#### Error Response (503)
Returned if GitHub App credentials are not configured.
- **owner** (string) - GitHub repository owner.
- **name** (string) - GitHub repository name.
- **accessible** (boolean) - Always `false`.
- **default_branch** (string) - Null.
- **private** (boolean) - Null.
- **permissions** (object) - Null.
- **install_url** (string) - Null.

#### Error Response Example
```json
{
  "owner": "acme-corp",
  "name": "my-app",
  "accessible": false,
  "default_branch": null,
  "private": null,
  "permissions": null,
  "install_url": null
}
```
```

--------------------------------

### Server startup: Compute and store ServerSettings

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-04-22-001-refactor-settings-api-entrypoints-plan.md

This code demonstrates how to compute and store ServerSettings during server startup. It uses `apply_runtime_settings` to get effective settings and then derives `ServerSettings` from this layer, storing it in AppState.

```rust
let effective_settings = apply_runtime_settings(&disk_settings, &args, &data_dir);
let server_settings = ServerSettings::from_layer(&effective_settings)?;
// ... thread server_settings into AppState
```

--------------------------------

### Configure HTTP Hook

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/changelog/2026-03-05.mdx

Example of configuring an HTTP hook to trigger an action before a stage starts. It specifies the URL and TLS mode for the webhook.

```toml
[[hooks]]
event = "stage.before"
executor = "http"
url = "https://api.example.com/webhook"
tls_mode = "strict"
```

--------------------------------

### Install Fabro with One-Line Script

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/changelog/2026-03-10.mdx

Use this command to download the installer script and execute it. It automatically detects your platform and sets up the Fabro binary in your PATH.

```bash
curl -fsSL https://raw.githubusercontent.com/fabro-sh/fabro/main/install.sh | bash
fabro install
```

--------------------------------

### Run Daemon Startup Tests

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-02-server-readiness-timeouts.md

Execute the unit tests for the server start command and the `cmd::server_start` integration test to ensure the new readiness check mechanism functions correctly and does not introduce regressions.

```bash
cargo nextest run -p fabro-cli 'commands::server::start::tests' --status-level fail --final-status-level fail --show-progress none
cargo nextest run -p fabro-cli 'cmd::server_start' --status-level fail --final-status-level fail --show-progress none
```

--------------------------------

### Fabro Run Interact Action Enum

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-05-11-add-fabro-mcp-server.md

Defines the possible actions that can be performed on a Fabro run, such as getting details, starting, messaging, or archiving.

```rust
#[derive(Debug, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
enum RunInteractAction {
    Get,
    Start,
    Message,
    Cancel,
    Archive,
    Unarchive,
    GetQuestions,
    Answer,
}
```

--------------------------------

### Full settings.toml Reference

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/administration/server-configuration.mdx

This is a comprehensive example of the settings.toml file, illustrating various server configuration options including listening addresses, API and web URLs, authentication methods, sandbox providers, storage, artifacts, and logging levels. It also includes default run configurations for models, preparation steps, and environments.

```toml
_version = 1

[server.listen]
type = "tcp"
address = "0.0.0.0:3000"

[server.api]
url = "https://fabro.example.com/api/v1"

[server.web]
enabled = true
url = "https://fabro.example.com"

[server.auth]
methods = ["dev-token", "github"]

[server.auth.github]
allowed_usernames = ["alice", "bob"]

[server.sandbox.providers.local]
enabled = true

[server.sandbox.providers.docker]
enabled = true

[server.sandbox.providers.daytona]
enabled = true

[server.integrations.github]
app_id = "123456"
client_id = "Iv1.abc123"

[server.integrations.github.webhooks]
strategy = "tailscale_funnel"

[server.storage]
root = "/var/lib/fabro"

[server.artifacts]
provider = "s3"
prefix = "artifacts"

[server.artifacts.s3]
bucket = "my-fabro-data"
region = "us-east-1"

[server.slatedb]
provider = "s3"
prefix = "slatedb"
disk_cache = true

[server.slatedb.s3]
bucket = "my-fabro-data"
region = "us-east-1"

[server.scheduler]
max_concurrent_runs = 8

[server.logging]
level = "info"

# Run defaults — applied to every run unless overridden by workflow/project config
[run.model]
name = "claude-sonnet-4-5"
provider = "anthropic"
fallbacks = ["gemini", "openai"]

[[run.prepare.steps]]
script = "npm install"

[run.environment]
id = "cloud"

[environments.cloud]
provider = "daytona"

[environments.cloud.lifecycle]
auto_stop = "60m"

[environments.cloud.labels]
team = "platform"

[run.checkpoint]
exclude_globs = ["**/node_modules/**", "**/.cache/**"]
skip_git_hooks = false

[run.inputs]
default_branch = "main"

[run.git.author]
name = "fabro-bot"
email = "fabro-bot@company.com"

```

--------------------------------

### Example Usage of Storage Override

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-04-23-003-refactor-config-types-boundary-and-dense-migration-plan.md

Demonstrates how to chain loading settings with applying a storage override.

```rust
ServerSettingsBuilder::load_from(&path)?.with_storage_override(&dir)
```

--------------------------------

### Define a Pre-check Hook

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/execution/run-configuration.mdx

Example of defining a hook that runs a script before a stage starts. It specifies the script path, event, and other configurations like blocking and timeout.

```toml
[[run.hooks]]
id = "pre-check"
name = "Pre-check script"
event = "stage_start"
script = "./scripts/pre-check.sh"
matcher = "agent"
blocking = true
timeout = "30s"
sandbox = false
```

--------------------------------

### GET /install/session

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/specs/2026-04-18-web-install-design.md

Retrieves the current installation session snapshot, including completed steps and recorded values (with secrets redacted). This is used by the frontend to rehydrate the UI on mount.

```APIDOC
## GET /install/session

### Description
Returns the current `PendingInstall` snapshot — completed steps, recorded values (with secrets redacted), prefill data (canonical URL from forwarded headers, etc.). Frontend calls on mount to rehydrate.

### Method
GET

### Endpoint
/install/session

### Response
#### Success Response (200)
- **InstallSession** (object) - The installation session snapshot.
```

--------------------------------

### Example Run Directory Path

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/run-directory.mdx

Illustrates the naming format for a per-run directory under the default storage location.

```bash
~/.fabro/storage/scratch/20260307-01JQXYZ123ABC456DEF789/
```

--------------------------------

### Initialize Fabro project

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/getting-started/quick-start.mdx

Navigate to your repository and run this command to initialize a new Fabro project. This creates necessary configuration files and a starter workflow.

```bash
cd my-repo/
fabro repo init
```

--------------------------------

### Agent Transition Example with Prompt

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/workflows/transitions.mdx

This DOT language example shows how to configure a 'review' node to prompt the LLM for specific JSON responses to guide transitions. The prompt instructs the LLM to output either '{"preferred_next_label": "fix"}' or '{"preferred_next_label": "approve"}'.

```dot
review [
    label="Review",
    shape=tab,
    prompt="Review the implementation for correctness and \n        code quality. If changes are needed, respond with: \n        {\"preferred_next_label\": \"fix\"}. If everything \n        looks good, respond with: \n        {\"preferred_next_label\": \"approve\"}."
]

review -> fix     [label="Fix"]
review -> approve [label="Approve"]
```

--------------------------------

### Basic `fabro` Run Lifecycle Commands

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/changelog/2026-03-20.mdx

Demonstrates the sequence of commands for creating a run directory, starting the engine process, and attaching to observe progress.

```bash
fabro create my-workflow --goal "Implement feature X"
fabro start <run-id>
fabro attach <run-id>
```

--------------------------------

### PUT /install/server

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/specs/2026-04-18-web-install-design.md

Records the canonical URL confirmation into the installation session.

```APIDOC
## PUT /install/server

### Description
Records canonical URL confirmation.

### Method
PUT

### Endpoint
/install/server

### Parameters
#### Request Body
- **ServerConfigInput** (object) - Required - An object containing the server configuration details.
```

--------------------------------

### Start Fabro API Server and Web UI

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/reference/architecture.mdx

Instructions to start the Fabro API server and the React-based web UI for development. The API server defaults to using a socket file, and the web UI requires navigating to its directory and running a development server command.

```bash
fabro server start                 # API on ~/.fabro/fabro.sock by default
cd apps/fabro-web && bun run dev   # rebuilds web assets on change; refresh the browser
```

--------------------------------

### RunPairStatusResponse JSON Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-18-server-side-run-pairing-api-events.md

Response for retrieving run pair status, including the current active pair and a list of eligible targets. Used by the GET /api/v1/runs/{id}/pair endpoint.

```json
{
  "run_id": "01HZX6M0P7SE4VJ9Y3X2B8E9QF",
  "current_pair": null,
  "targets": [
    {
      "stage_id": "code@1",
      "node_id": "code",
      "node_label": "Code",
      "visit": 1,
      "agent_session_id": "ses_01",
      "provider": "openai",
      "model": "gpt-5.3"
    }
  ]
}
```

--------------------------------

### Install Mode Bootstrapping Logic

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/specs/2026-04-18-web-install-design.md

Illustrates the conditional logic for entering install mode based on configuration path and file presence. It highlights the asymmetry in handling explicit vs. implicit configuration paths.

```rust
lib/crates/fabro-cli/src/commands/server/mod.rs:31
```

```rust
fabro-config/src/user.rs:77
```

```rust
fabro-server/src/serve.rs:820-824
```

```rust
tests/it/cmd/server_start.rs:111
```

```rust
fabro-config/src/user.rs:81-112
```

--------------------------------

### PairRecord JSON Example

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-18-server-side-run-pairing-api-events.md

Represents a record of a pairing session, including its status, start and end times, and the target involved. Nullable fields like ended_at and failure_reason provide details on session lifecycle.

```json
{
  "pair_id": "01HZX6M29F1CD5YYMHT1F5D7WQ",
  "run_id": "01HZX6M0P7SE4VJ9Y3X2B8E9QF",
  "status": "active",
  "started_at": "2026-05-18T12:00:01Z",
  "ended_at": null,
  "failure_reason": null,
  "target": {
    "stage_id": "code@1",
    "node_id": "code",
    "node_label": "Code",
    "visit": 1,
    "agent_session_id": "ses_01",
    "provider": "openai",
    "model": "gpt-5.3"
  }
}
```

--------------------------------

### GET /install/github/app/redirect

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/specs/2026-04-18-web-install-design.md

GitHub manifest-conversion redirect target. This endpoint is authorized by validating the `state` query parameter against the install session, as it is not protected by install-token middleware. It exchanges `code` for App credentials and stores them in the session.

```APIDOC
## GET /install/github/app/redirect

### Description
GitHub manifest-conversion redirect target. **Not protected by install-token middleware** — GitHub strips Authorization headers, so this endpoint can only be authorized by validating the `state` query param against the install session. The handler validates `state`, then exchanges `code` via `POST https://api.github.com/app-manifests/{code}/conversions` to obtain the App's `id`, `slug`, `client_id`, `client_secret`, `webhook_secret`, and `pem`. Stores them in the session. Responds with a 302 to `/install/github/done?token=<install_token>` so the SPA picks back up with the token re-attached to the URL.

### Method
GET

### Endpoint
/install/github/app/redirect

### Parameters
#### Query Parameters
- **code** (string) - Required - The authorization code received from GitHub.
- **state** (string) - Required - The state parameter used for validation.
```

--------------------------------

### Update CLI Examples for Command-Local Target Selection

Source: https://github.com/fabro-sh/fabro/blob/main/docs/plans/2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md

Examples in CLI reference documentation are updated to use command-local placement for server URL and storage directory.

```bash
fabro model list --server-url ...
```

```bash
fabro server start --storage-dir ...
```

--------------------------------

### Initialize Fabro Project Configuration

Source: https://github.com/fabro-sh/fabro/blob/main/docs/public/changelog/2026-03-10.mdx

Run `fabro init` to generate a default `fabro.toml` file, setting up essential configurations for workflows, pull requests, and sandboxes.

```bash
fabro init
```

--------------------------------

### Web Install Finish Test: Skipped LLMs

Source: https://github.com/fabro-sh/fabro/blob/main/docs/superpowers/plans/2026-05-14-optional-llm-install.md

Add a browser-install finish test to assert that after skipping LLM setup, the `/install/finish` endpoint returns success, no LLM credentials are written to the vault, but GitHub secrets persist.

```rust
#[tokio::test]
async fn test_finish_with_skipped_llm() {
    let client = TestClient::new();

    // Simulate skipping LLM setup
    client.put("/install/llm")
        .json(&json!({ "providers": [] }))
        .send()
        .await;

    // Simulate completing other required steps (e.g., GitHub)
    client.put("/install/github")
        .json(&json!({ "token": "fake-github-token" }))
        .send()
        .await;

    // Finish the installation
    let response = client.post("/install/finish")
        .send()
        .await;

    assert_eq!(response.status(), StatusCode::OK);

    // Assert settings and runtime auth secrets are written (details omitted for brevity)

    // Assert no LLM credential entries are written to the vault
    let vault_entries: Vec<VaultEntry> = client.get("/vault")
        .send()
        .await
        .json()
        .await;
    assert!(vault_entries.iter().all(|entry| entry.key != "llm_api_key"));

    // Assert GitHub secrets still persist normally (details omitted for brevity)
}
```

--------------------------------

### Start Astro dev server for marketing site

Source: https://github.com/fabro-sh/fabro/blob/main/AGENTS.md

Starts the Astro development server for the marketing site located in `apps/marketing`.

```bash
cd apps/marketing && bun run dev
```

--------------------------------

### Install Fabro with Codex

Source: https://github.com/fabro-sh/fabro/blob/main/README.md

Install Fabro using Codex by piping the installation script to codex. Ensure you have curl and codex installed.

```bash
# With Codex
codex "$(curl -fsSL https://fabro.sh/install.md)"
```

--------------------------------

### Install Fabro with Bash

Source: https://github.com/fabro-sh/fabro/blob/main/README.md

Install Fabro directly using a bash script. Ensure you have curl and bash installed.

```bash
# With Bash
curl -fsSL https://fabro.sh/install.sh | bash
```