Fullsend

https://github.com/fullsend-ai/fullsend
Admin
Fullsend is a design exploration for enabling fully autonomous agentic software development on...
Tokens:1,383,927
Snippets:7,703
Trust Score:3.8
License:Apache-2.0
Update:3 days ago
Show doc for...
Tokens:
Raw
### otel-gui local quickstart

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/tracing.md

Starts otel-gui with OTLP/HTTP support on port 4318. UI available at localhost:4318.

```bash
podman run -p 4318:4318 ghcr.io/metafab/otel-gui:latest
```

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

### MLflow local quickstart

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/tracing.md

Starts MLflow server (>= 3.6) with OTLP/HTTP support. UI available at localhost:5000.

```bash
uvx mlflow server
```

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

### Install dependencies and start dev server

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/doc-site.md

Run `npm ci` to install dependencies, then `npm run docs:dev` to start the VitePress dev server at `http://localhost:5173/docs/`. Submodules are initialized automatically before the server starts.

```bash
npm ci
npm run docs:dev
```

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

### Arize Phoenix local quickstart

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/tracing.md

Starts Arize Phoenix with OTLP/HTTP support on ports 6006 and 4318. UI available at localhost:6006.

```bash
podman run -p 6006:6006 -p 4318:4318 arizephoenix/phoenix
```

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

### Fullsend GitHub Setup Command

Source: https://github.com/fullsend-ai/fullsend/blob/main/web/public/index.html

Run this command to enroll your repositories with the Fullsend agent pipeline. It is part of the 'Getting Started' steps, after installing the GitHub App.

```bash
$ fullsend github setup
```

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

### Jaeger local quickstart

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/tracing.md

Starts Jaeger with OTLP/HTTP support on ports 16686 and 4318. UI available at localhost:16686.

```bash
podman run -p 16686:16686 -p 4318:4318 jaegertracing/jaeger
```

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

### Preview and install fresh repository

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Runs status and dry-run install with credentials, then performs the real install. The dry-run never writes anything; install stops before any manifest or forge write if a configuration file needs action.

```bash
fullsend repos status --repo acme/api
fullsend repos install acme/api --dry-run \
  --vertex-project "<gcp-project>" --vertex-wif-provider "<wif-provider>"
fullsend repos install acme/api \
  --vertex-project "<gcp-project>" --vertex-wif-provider "<wif-provider>"
```

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

### Set manifest fields and install a repo

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Example of using `fullsend repos set` to create a manifest and then installing a repository with `fullsend repos install`. The first `repos set` writes `version: 1` to the manifest.

```bash
fullsend repos set defaults.inference.auth vertex-wif
```

```bash
fullsend repos set 'github.repos["acme/api"]' '{}'
```

```bash
fullsend repos install acme/api --vertex-project "<gcp-project>"
```

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

### One-time setup for macOS with Podman

Source: https://github.com/fullsend-ai/fullsend/blob/main/hack/ci-local/README.md

Preferred setup for macOS. Installs Podman, initializes a machine with 4 CPUs and 8 GB memory, and starts it.

```bash
brew install podman && podman machine init --cpus 4 --memory 8192 && podman machine start
```

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

### Output of fullsend inference provision

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/getting-inference.md

Example output from the provisioning command. It shows the WIF Provider value that you must pass to the GitHub setup command.

```text
⚡ fullsend <version>
  Autonomous agentic development for Git-hosted organizations

→ Provisioning WIF for repo-scoped inference: <org>/<repo>

  • Provisioning WIF infrastructure
  ✓ WIF infrastructure ready

    WIF Provider: projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/gh-<org>-<repo>

    Pass this value to the GitHub setup command:
      fullsend github setup <org>/<repo> \
        --inference-project=<gcp-project> \
        --inference-wif-provider=projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/gh-<org>-<repo>
```

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

### Preview and install GitLab project

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/configuring-gitlab.md

Previews the installation with --dry-run, then installs the project. Requires --vertex-project unless declared once via fullsend repos set gitlab.config.inference.project.

```bash
fullsend repos install <group/project> --dry-run --vertex-project "<gcp-project>"
fullsend repos install <group/project> --vertex-project "<gcp-project>"
```

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

### v1.7.0 startup log with read-only config warnings

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/inference-gateway-operator.md

This output is from a local run of the v1.7.0 image with the step 3 config. It shows two warnings before 'started bind' when the config is mounted read-only, as on Cloud Run. Both warnings are harmless for this setup; the session key only encrypts MCP session IDs, and this gateway serves no MCP.

```text
warn	config	failed to write generated session key	err=failed to write to file `/etc/agw-config/config.yaml`: Read-only file system (os error 30) path=/etc/agw-config/config.yaml
warn	config	no session key configured; MCP session IDs are not encrypted. Set SESSION_KEY or config.session.key
info	proxy::gateway	started bind	bind="bind/8080"
```

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

### Copy settings to keep into repos.yaml entry

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Shows the settings to copy into the entry's 'config' (or into 'github.config' / 'defaults.config' when they apply more widely). Omitted settings fall back to the preset and code defaults. Include 'mint_url' and the 'inference' values: install now derives FULLSEND_MINT_URL, FULLSEND_GCP_REGION, and the GCP secrets from them, so a setup install whose project and provider lived only in its configuration migrates without '--vertex-*' flags.

```yaml
    - name: acme/api
      inference:
        auth: vertex-wif
      config:
        runtime: pi
        roles: [triage, review]
        inference:
          project: my-gcp-project
          region: us-east5
          wif_provider: projects/123456789/locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc
```

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

### Setup output for inference gateway

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/inference-gateway.md

Shows the expected output when running the setup command with inference gateway flags. It verifies token permissions, creates a scaffold PR, sets repository variables and secrets, and completes the per-repo setup.

```text
⚡ fullsend <version>
  Autonomous agentic development for Git-hosted organizations

→ Setting up per-repo fullsend for example-org/example-repo

    Updating existing .fullsend/config.yaml: inference.gateway (other keys kept; comments are not preserved)
  • Checking token permissions
  ✓ Token permissions verified

  • Creating scaffold PR for example-org/example-repo (target: main)
    User example-user has write access — pushing directly to example-org/example-repo
  ✓ Created PR #1: https://github.com/example-org/example-repo/pull/1
    Merge the PR to apply these changes
  • Configuring repository variables
  ✓ Set 5 repository variables
  • Configuring repository secrets
  ✓ Set 0 repository secrets

  ✓ Per-repo setup complete for example-org/example-repo
```

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

### Pass Provider to Installer

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/advanced-setup.md

Runs 'fullsend github setup' with the custom WIF provider and project. Requires WIF_PROVIDER and MINT_URL environment variables. The provider is constructed from the project number and pool/provider names.

```bash
export WIF_PROVIDER="projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/fullsend-inference/providers/github-oidc"

fullsend github setup "$ORG_NAME/$REPO_NAME" \
  --inference-project "$GCP_PROJECT" \
  --inference-wif-provider "$WIF_PROVIDER" \
  --mint-url "$MINT_URL"
```

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

### Per-Repo Install Pipeline diagram

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/cli-internals.md

ASCII diagram of the unified per-repo installation pipeline. It shows the five phases: Discover (read-only), App setup (shared runAppSetup), Mint provisioning, WIF provisioning, and writing scaffold/config files. Includes delivery modes for CommitScaffoldFiles: default PR mode and --direct with fallback on ErrBranchProtected.

```text
┌─────────────────────────────────────────────────────────────────┐
│                   Per-Repo Install Pipeline                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  fullsend admin install <owner/repo>                            │
│  ┌──────────────────────┐                                       │
│  │ Parse target          │                                      │
│  │  "acme/repo" → repo  │                                       │
│  │  "acme"      → error │                                       │
│  └──────────┬───────────┘                                       │
│             ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phase 1: Discover (read-only)                              │ │
│  │                                                            │ │
│  │  a. Discover mint   --mint-url / --mint-project / default  │ │
│  │     └─ DiscoverMint() → check if GCF exists, get URL       │ │
│  │  b. Resolve existing app IDs from mint env vars            │ │
│  │     └─ ROLE_APP_IDS (role → app ID, shared) → skip app     │ │
│  │        creation when all roles are present                 │ │
│  └──────────┬─────────────────────────────────────────────────┘ │
│             ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phase 2: App setup (shared: runAppSetup)                   │ │
│  │                                                            │ │
│  │  For each role in --agents:                                │ │
│  │    - Create/reuse GitHub App ({appSet}-{role} --app-set)   │ │
│  │    - Download PEM key from App creation flow               │ │
│  │    - Store PEM in GCP Secret Manager                       │ │
│  │    - Record App ID + Client ID                             │ │
│  │                                                            │ │
│  │  Shared code: runAppSetup() → []AgentCredentials           │ │
│  └──────────┬─────────────────────────────────────────────────┘ │
│             ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phase 3: Mint provisioning                                 │ │
│  │                                                            │ │
│  │  If mint not found → deploy GCF (Provision)                │ │
│  │  If mint exists    → verify mint URL (verifyMintURL)       │ │
│  │                    → store PEMs in Secret Manager          │ │
│  │                                                            │ │
│  │  Uses gcf.NewProvisioner with a shared Config{}            │ │
│  └──────────┬─────────────────────────────────────────────────┘ │
│             ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phase 4: WIF provisioning (inference auth)                 │ │
│  │                                                            │ │
│  │  ProvisionWIF() → create pool, provider, IAM               │ │
│  │  Repo-scoped WIF provider (mintcore.BuildRepoProviderID)   │ │
│  └──────────┬─────────────────────────────────────────────────┘ │
│             ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ Phase 5: Write scaffold + config files                     │ │
│  │                                                            │ │
│  │  CommitScaffoldFiles() delivery modes:                     │ │
│  │    Default (PR):  create feature branch → commit → open PR │ │
│  │    --direct:      try CommitFiles (default branch)         │ │
│  │      if ErrBranchProtected → fall back to PR mode          │ │
│  │  ┌──────────────────────────────────────────┐              │ │
│  │  │ Write .fullsend/ dir in the target repo  │              │ │
│  │  │ Push shim workflow template              │              │ │
│  │  │ Vendor fullsend binary (opt)             │              │ │
│  │  └──────────────────────────────────────────┘              │ │
│  └──────────┬─────────────────────────────────────────────────┘ │
│             ▼                                                   │
```

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

### Base harness example

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/ADRs/0070-portable-provider-profile-resolution.md

YAML example of a base harness declaring openshell.profiles and providers with remote URLs.

```yaml
# Base harness at https://github.com/org/shared-harness/harness.yaml
agent: agents/code.md
policy: policies/default.yaml  # openshell policy
openshell:
  profiles:
  - "https://github.com/org/profiles/tree/main/claude-code.yaml#sha256=aaa..."
  - "https://github.com/org/profiles/tree/main/github.yaml#sha256=bbb..."
providers:
  - "https://github.com/org/providers/tree/main/claude.yaml#sha256=ccc..."
```

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

### Install apps on a new pool org

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/e2e-testing.md

Use the public install URLs to install the six fullsend-test-* apps plus the production fullsend-ai-e2e app. Select the target pool org and grant access to 'All repositories'.

```bash
# Install the six fullsend-test-* apps from the inventory table above, plus
# the production fullsend-ai-e2e app required for cross-org suite control:
# https://github.com/apps/<slug>/installations/new
# Select the target pool org and grant access to "All repositories".
```

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

### Declare and install GitLab project

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Sets the GitLab instance URL, declares the project, and runs dry-run and real install with an OpenAI API key. Use the same steps as for GitHub but with gitlab.* keys.

```bash
fullsend repos set gitlab.url https://gitlab.com
fullsend repos set gitlab.inference.auth openai-api-key
fullsend repos set 'gitlab.repos["group/project"]' '{}'
fullsend repos install group/project --dry-run --openai-api-key "$OPENAI_API_KEY"
fullsend repos install group/project --openai-api-key "$OPENAI_API_KEY"
```

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

### Declare repository with manifest-level settings

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Declares the repository with its manifest-level settings, such as inference.auth, app_set, fullsend_ref, and vendor. This is the first step in adopting a repository installed with 'github setup'.

```bash
fullsend repos set 'github.repos["acme/api"]' '{"inference": {"auth": "vertex-wif"}}'
```

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

### Install binary locally with install-binary.sh

Source: https://github.com/fullsend-ai/fullsend/blob/main/skills/cutting-releases/SKILL.md

Run this script from the repo root to install the binary locally. The script downloads the archive, verifies its SHA-256 checksum, and installs the binary as `fullsend-<tag>` so multiple versions can coexist. The default install directory is `~/.local/bin/`.

```bash
bash skills/cutting-releases/scripts/install-binary.sh <tag> [install-dir]
```

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

### Extend fullsend-sandbox with additional tools

Source: https://github.com/fullsend-ai/fullsend/blob/main/images/README.md

Per-org images that need additional tools should extend fullsend-sandbox or fullsend-code. This example installs rustc and cleans up apt lists.

```dockerfile
FROM ghcr.io/fullsend-ai/fullsend-sandbox:latest
RUN apt-get update && apt-get install -y --no-install-recommends rustc && rm -rf /var/lib/apt/lists/*
```

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

### Verify adoption and install

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Runs 'fullsend repos status --repo acme/api' again to check for ordinary drift or none, then previews and installs. Install rejects a rewrite that makes the effective configuration less restrictive than the current one unless 'repos.yaml' declares that relaxation. The compared keys are 'kill_switch', 'roles', 'allowed_remote_resources', agent 'enabled: false' suppressions, 'tracker.<provider>.allowed_targets', 'inference.gateway.url', and 'inference.gateway.audience'.

```bash
fullsend repos status --repo acme/api
```

```bash
fullsend repos install acme/api --dry-run
```

```bash
fullsend repos install acme/api
```

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

### Check OpenShell installation and gateway

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/running-agents-locally.md

Verify OpenShell is installed and the gateway is running. Use `openshell --version` to check installation and `openshell gateway list` to verify the gateway.

```bash
openshell --version
```

```bash
openshell gateway list
```

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

### fullsend admin install CLI usage for per-org and per-repo modes

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/ADRs/0033-per-repo-installation-mode.md

Shows the two argument formats for the fullsend admin install command. The first uses an org name for per-org installation, the second uses owner/repo for per-repo installation. The comment lines indicate the mode for each command.

```bash
fullsend admin install <org>            # per-org installation
fullsend admin install <owner/repo>     # per-repo installation
```

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

### First install output

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/configuring-gitlab.md

Shows the output of a first install, including setting repository variables and secrets, creating a merge request, and a summary line. The merge request must be merged for changes to take effect.

```text
    [group/project] Set 2 repository variables
    [group/project] Set 2 repository secrets
  ✓ Created PR #1: https://gitlab.example.com/group/project/-/merge_requests/1
    Merge the PR to apply these changes
  ✓ Install complete: 1 installed, 0 converged, 0 already current, 0 failed
```

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

### Create repos.yaml with fullsend repos set and install

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/repo-management.md

Use these commands to create and populate the repos.yaml manifest. The first repos set creates the manifest with version: 1; repos install does not create the manifest or add entries, and a missing manifest is an error.

```bash
fullsend repos set defaults.inference.auth vertex-wif
fullsend repos set 'github.repos["acme/api"]' '{}'
fullsend repos set 'github.repos["acme/web"]' '{}'
fullsend repos install --direct --vertex-project "<gcp-project>"
```

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

### Install repos with glob pattern and concurrency

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/repo-management.md

Installs repositories matching a glob pattern with direct delivery and 8 concurrent operations. Requires credentials only for the selected repositories' forges; installing the whole manifest requires credentials for every forge.

```bash
fullsend repos install "acme/*" --direct --concurrency 8
```

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

### fullsend repos install commands

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Install repositories from a manifest. Use --dry-run to preview, pass positional selectors to filter, and use --direct with --concurrency for parallel installs.

```bash
fullsend repos install -f repos.yaml
fullsend repos install --dry-run
fullsend repos install acme/api acme/web
fullsend repos install "acme/*" --direct --concurrency 8
```

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

### Run per-repo install

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/ADRs/0044-deprecate-per-org-installation-mode.md

Command to install per-repo shim workflow and configuration for a specific repository.

```bash
fullsend admin install <owner>/<repo> \
  --mint-url <existing-mint-url> \
  --inference-project <existing-project> \
  --skip-app-setup \
  --skip-mint-deploy
```

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

### fullsend repos status command examples

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Read-only comparison of the repos.yaml manifest against actual forge state. Reports installation status and configuration drift for each repo, including declared configuration-preset drift against .fullsend/config.base.yaml and managed configuration drift against .fullsend/config.yaml. An existing .fullsend/config.base.yaml with no resolved preset is reported as drift. Both configuration files are checked even for a repo with no fullsend components yet: an undeclared base, a differing preset base, or a managed .fullsend/config.yaml that lacks the ownership marker is reported before first install. Files that install would simply add are not reported as missing until the repo is installed. An existing zero-byte .fullsend/config.yaml counts as an existing markerless file, so it also requires adoption. For every markerless overlay, the table and the JSON detail field show the proposed repos.yaml entry that carries each existing setting (all under the entry's config, including runtime, allowed_remote_resources, and values equal to the code defaults) the setting-level difference between the existing file and the managed file adoption would produce, and the effective layered-configuration change (the existing overlay over the installed base compared with the managed overlay over the base layer the run would leave in place), so the operator can see which settings would be lost, or would change only through the base layer, before adopting. A markerless overlay that is malformed or not a per-repo configuration is reported as a status error rather than adoption guidance.

```bash
fullsend repos status
fullsend repos status -f path/to/repos.yaml
fullsend repos status --repo acme/api --repo acme/web
fullsend repos status --repo "acme/*" --json
```

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

### Example minimal CLAUDE.md

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/problems/contributor-guidance.md

A minimal CLAUDE.md example that references CONTRIBUTING.md for full guidelines and includes non-obvious points and BOOKMARKS.md references. Keep under 60 lines to avoid performance degradation.

```markdown
See CONTRIBUTING.md for full contribution guidelines. Key non-obvious points:

- API changes: see CONTRIBUTING.md#api-changes. Always check architecture repo.
- We had production incidents from unvalidated fields in Q3 2024 - all new fields need validation.
- Cross-repo impact: if changing shared schemas, downstream consumers likely need updates.

See BOOKMARKS.md for architectural context and external standards.
```

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

### First org: admin install with custom app set prefix

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/mint-administration.md

Runs admin install with --app-set to name public apps with a custom prefix, e.g., {first-org}-fullsend. Use when the first org uses a custom app set prefix.

```bash
fullsend admin install "$FIRST_ORG/$FIRST_REPO" \
  --mint-url "$MINT_URL" \
  --inference-wif-provider "$WIF_PROVIDER" \
  --inference-project "$GCP_PROJECT" \
  --public \
  --app-set "$FIRST_ORG"
```

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

### Declare a new repo, then install it

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Declares a new GitHub repo with Vertex WIF inference auth, then installs it directly with a specified GCP project.

```bash
fullsend repos set 'github.repos["acme/new-repo"]' '{"inference": {"auth": "vertex-wif"}}'
fullsend repos install acme/new-repo --direct --vertex-project "<gcp-project>"
```

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

### First org: deploy mint, enroll repo, provision inference, configure GitHub with public apps

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/mint-administration.md

Sets up the first GitHub organization by deploying the token mint, enrolling the first repository, provisioning inference WIF, and configuring the repository with public GitHub Apps. Requires environment variables FIRST_ORG, FIRST_REPO, GCP_PROJECT, MINT_URL (from deploy output), and WIF_PROVIDER (from inference status). The --public flag creates public unlisted apps installable by other orgs. admin install prints a deprecation warning but still creates all role apps in one run.

```bash
export FIRST_ORG="<first-github-org>"
export FIRST_REPO="<first-github-repo>"
export GCP_PROJECT="<your-gcp-project>"

# 1. Deploy the token mint
fullsend mint deploy --project="$GCP_PROJECT" --pem-dir=/path/to/pems

# 2. Enroll the first repository in the mint
fullsend mint enroll "$FIRST_ORG/$FIRST_REPO" --project="$GCP_PROJECT"

# 3. Provision inference WIF for the repository. Use the same owner/repo
#    target as the GitHub setup in step 4, so the Vertex AI role is granted to
#    that repository. Repeat this step for each repository you configure.
fullsend inference provision "$FIRST_ORG/$FIRST_REPO" --project="$GCP_PROJECT"

# 4. Configure a repository and create public apps (installable by other orgs).
#    `github setup` does not create GitHub Apps, so use `admin install`, which
#    creates the apps (as public with --public) and configures the repository.
#    It targets a single owner/repo; repeat per repository. `admin install`
#    prints a deprecation warning; it still creates every role's app in one
#    run. To create apps one role at a time on the deployed mint, use
#    `fullsend mint add-role <role> --project "$GCP_PROJECT" --org "$FIRST_ORG"`
#    (add --public / --app-set as needed).
# $MINT_URL: the "Mint deployed at ..." URL printed by step 1.
# $WIF_PROVIDER: the FULLSEND_GCP_WIF_PROVIDER value from step 3 — run
#   `fullsend inference status "$FIRST_ORG/$FIRST_REPO" --project="$GCP_PROJECT" --format=env`
#   and copy it, or parse it from `--format=json`.
fullsend admin install "$FIRST_ORG/$FIRST_REPO" \
  --mint-url "$MINT_URL" \
  --inference-wif-provider "$WIF_PROVIDER" \
  --inference-project "$GCP_PROJECT" \
  --public
```

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

### Configure OpenAI WIF auth and install repository

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/openai-workload-identity.md

Declares the `openai-wif` inference auth method for a repository in a `repos.yaml` manifest, then installs it. No `FULLSEND_GCP_PROJECT_ID`, `FULLSEND_GCP_WIF_PROVIDER`, or `FULLSEND_OPENAI_API_KEY` is required. The method is rejected for GitLab repositories.

```bash
fullsend repos set 'github.repos["acme/api"]' '{"inference": {"auth": "openai-wif"}}'
fullsend repos install acme/api
```

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

### fullsend repos install command syntax

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Shows the command-line syntax for the `fullsend repos install` subcommand, which converges repositories to the desired state defined in a `repos.yaml` manifest.

```bash
fullsend repos install [repos...] [flags]
```

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

### Create a new agent with fullsend agent new

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/bring-your-own-agent.md

Generates all agent files and registers the agent. Requires the fullsend CLI on PATH and a repository scaffolded with `fullsend github setup` (or `fullsend repos install` for GitLab). The example creates agent 'lint-docs' with role 'triage' and a description.

```bash
fullsend agent new lint-docs \
  --role triage --description "Check docs changes for broken links"
```

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

### Verify and commit manifest after install

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/migrating-from-github-setup.md

Checks repository status and reviews the repos.yaml diff. A first install without a preset records config.tracker.github.allowed_targets.repos and writes github.fullsend_ref when unset; commit both.

```bash
fullsend repos status --repo acme/api
git diff repos.yaml
```

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

### fullsend github setup with vendor preset

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/advanced-setup.md

Use when a platform operator provides a vendor preset (config.base.yaml) and you need to pass persistent setup flags that override preset values. Requires --config and --config-hash for the preset, plus --inference-project and --inference-wif-provider.

```bash
fullsend github setup <owner/repo> \
  --inference-project "<GCP_PROJECT>" \
  --inference-wif-provider "<WIF_PROVIDER>" \
  --config "<preset-path-or-url>" \
  --config-hash "<sha256-hex>"
```

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

### Check repository status with fullsend repos status

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/configuring-gitlab.md

Run this command to compare the manifest against the project and verify installation status. The output shows whether each repository is installed and whether drift exists.

```bash
fullsend repos status -f repos.yaml
```

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

### Run TestOpenAIWIFLiveInstallAndRun

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/openai-workload-identity.md

Opt-in live integration test that installs workflows, checks readiness, and verifies a successful agent run. Requires a prepared repository with mint enrollment, FULLSEND_OPENAI_* variables, and a working OpenAI-model triage agent. Set GH_TOKEN, FULLSEND_OPENAI_WIF_LIVE_REPO, FULLSEND_OPENAI_WIF_LIVE_MINT_URL, and FULLSEND_OPENAI_WIF_LIVE_REF before running.

```bash
go test ./internal/cli -run '^TestOpenAIWIFLiveInstallAndRun$' -count=1 -v -timeout=25m
```

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

### Run setup script with --dry-run

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/e2e-testing.md

Preview changes to the durable inference gateway. Only reads, prints what it would change, and exits 3 if anything would change. Pass --with-vertex on every run.

```bash
hack/setup-e2e-inference-gateway.sh --project "$E2E_GCP_PROJECT_ID" --with-vertex --dry-run
```

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

### fullsend github setup with inference gateway

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/inference-gateway.md

Configures the inference gateway for a repository using the operator's values and model mappings. Pass the gateway URL, audience, and model mappings via flags. The setup updates the .fullsend/config.yaml and opens a pull request with the changes.

```bash
fullsend github setup example-org/example-repo \
  --inference-gateway-url https://gateway.example.com \
  --inference-gateway-audience fullsend-inference \
  --inference-gateway-model claude-sonnet-4-6=anthropic-messages \
  --inference-gateway-model gemini-2.5-flash=openai-completions
```

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

### Install Fullsend with Vertex WIF provider

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/configuring-gitlab.md

Use this command to install Fullsend for a GitLab group/project with a specified GCP project and WIF provider. Passing --vertex-wif-provider alongside --vertex-project requires no declaration. The GCP project must have Vertex AI APIs enabled.

```bash
fullsend repos install <group/project> \
  --vertex-project "<gcp-project>" \
  --vertex-wif-provider "projects/<number>/locations/global/workloadIdentityPools/fullsend-inference/providers/gitlab-oidc"
```

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

### Check and install managed configuration with fullsend repos

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/repo-management.md

Use `repos status` to report whole-file managed drift and `repos install` to rewrite the managed file. The `--dry-run` flag previews changes without writing. The `--json` flag outputs status as JSON.

```bash
fullsend repos status -f repos.yaml --json   # whole-file managed drift
```

```bash
fullsend repos install -f repos.yaml --dry-run
```

```bash
fullsend repos install -f repos.yaml         # rewrite the managed file
```

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

### Example output of remaining time calculation

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/run.md

Example console output from the preceding bash snippet, showing the remaining seconds as 161. This is the expected output when run under a three-minute budget by a probe agent about twenty seconds after its start.

```console
remaining=161
```

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

### Install vendor preset with --config and --config-hash

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/configuring-github.md

Installs a curated preset configuration. Commits preset as .fullsend/config.base.yaml; persistent flags override in .fullsend/config.yaml. --config-hash verifies SHA-256 for remote URLs. Only valid for per-repo mode.

```bash
fullsend github setup <org>/<repo> \
  --inference-project "<gcp-project>" \
  --inference-wif-provider "<wif-provider-url>" \
  --config "<path-or-url>" \
  --config-hash "<sha256-hex>"
```

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

### Create and provision a GCE VM (group-scoped runner)

Source: https://github.com/fullsend-ai/fullsend/blob/main/hack/gitlab-runner-vm/README.md

Creates a VM with a group-scoped GitLab runner. Requires gcloud CLI (authenticated), python3, and curl. By default, VMs have no public IP and SSH is tunneled via IAP; the Cloud IAP API must be enabled and the operator needs roles/iap.tunnelResourceAccessor. The VPC subnet must have Cloud NAT configured, otherwise dnf install will fail. Set GCP_USE_IAP=false to create the VM with an external IP and SSH directly. VMs get a 30 GiB boot disk whose root filesystem is grown and verified during provisioning.

```bash
GL_TOKEN=glpat-xxx GROUP_ID=12345 \
  GITLAB_URL=https://gitlab.example.com \
  GCP_PROJECT=my-gcp-project \
  RUNNER_IMAGE=ghcr.io/org/runner:v1.2.3 \
  ./create-gcp-vm.sh
```

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

### Upgrade from OpenShell 0.0.x: cleanup and install

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/running-agents-locally.md

Steps to upgrade from OpenShell 0.0.x to 0.1. Delete sandboxes, stop the old gateway, move config and state aside, write the new schema v2 config, then install with OPENSHELL_ACK_BREAKING_UPGRADE=1. On Homebrew, use `brew services stop/start openshell` instead of systemctl.

```bash
# 1. With the 0.0.x CLI: delete your sandboxes (they do not carry over)
openshell sandbox delete --all

# 2. Stop the 0.0.x gateway
systemctl --user stop openshell-gateway

# 3. Move the old config and gateway state aside
cfg="${XDG_CONFIG_HOME:-$HOME/.config}/openshell"
state="${XDG_STATE_HOME:-$HOME/.local/state}/openshell"
ts="$(date +%s)"
if [ -f "$cfg/gateway.toml" ]; then mv "$cfg/gateway.toml" "$cfg/gateway.toml.pre-0.1"; fi
for d in gateway tls; do
  if [ -d "$state/$d" ]; then mv "$state/$d" "$state/$d.pre-0.1.$ts"; fi
done

# 4. Write the schema v2 config shown above to "$cfg/gateway.toml", then install
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v${OPENSHELL_VERSION}/install.sh \
  | OPENSHELL_ACK_BREAKING_UPGRADE=1 OPENSHELL_VERSION=v${OPENSHELL_VERSION} sh
openshell sandbox list   # "No sandboxes found." means the new gateway is up
```

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

### Set up OTLP headers file for tracing

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/mint.md

Creates a file with one key=value per line in OTEL_EXPORTER_OTLP_HEADERS syntax. The file is used by the mint deploy command to configure tracing headers.

```bash
chmod 600 otlp-headers   # one key=value per line, OTEL_EXPORTER_OTLP_HEADERS syntax
```

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

### Use existing public apps from another app set with --app-set

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/advanced-setup.md

Pass the same --app-set value when installing public apps registered under a custom app set so the CLI resolves the correct slugs. The setup command detects that the public apps are already installed in the org (matched by app ID from the mint's ROLE_APP_IDS) and skips app creation — role PEM secrets are shared and already exist.

```bash
fullsend github setup "$NEW_ORG/$REPO_NAME" \
  --mint-url "$MINT_URL" \
  --inference-project "$GCP_PROJECT" \
  --inference-wif-provider "$WIF_PROVIDER" \
  --app-set fullsend-ai
```

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

### Lock file schema example (.fullsend/lock.yaml)

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/ADRs/0038-universal-harness-access.md

Example lock file format introduced in Phase 3. Pins all transitive dependencies with full URLs and integrity hashes. Includes fields for harness source, dependencies, and transitive dependencies.

```yaml
# .fullsend/lock.yaml
version: 1
generated_at: "2026-05-12T10:00:00Z"
harnesses:
  rust-linter:
    source: harness/rust-linter.yaml
    sha256: abc123...
    resolved_at: "2026-05-12T10:00:00Z"
    dependencies:
      - field: agent
        url: https://raw.githubusercontent.com/fullsend-ai/library/8cd3799.../agents/rust.md
        sha256: def456...
        type: file
        fetched_at: "2026-05-12T10:00:00Z"
      - field: skills[0]
        url: https://github.com/fullsend-ai/library/tree/8cd3799.../skills/cargo-check
        sha256: <tree-hash>...
        type: directory
        fetched_at: "2026-05-12T10:00:00Z"
        files:
          - path: SKILL.md
            sha256: abc123...
          - path: scripts/check.sh
            sha256: def456...
        transitive_deps:
          - field: skills[dep0]
            url: https://raw.githubusercontent.com/fullsend-ai/library/8cd3799.../policies/rust-sandbox.yaml
            sha256: jkl012...
            type: file
            fetched_at: "2026-05-12T10:00:00Z"
```

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

### Status Endpoint Non-OIDC Response

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/infrastructure-reference.md

Example JSON response from GET /v1/status when authenticated via a non-OIDC method (e.g., GitHub user token). Omits org and the former allowed_orgs field.

```json
{"roles": ["coder", "review", "triage"], "workflow_host_repos": ["fullsend-ai/fullsend"], "version": "2.0.0", "commit": "abc123"}
```

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

### Deploy a public mint with --public

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/mint-administration.md

Bootstraps a public mint by setting PER_REPO_WIF_REPOS=* and a permissive WIF provider CEL. Redeploying or upgrading must use the same mode; deploy rejects mode conversion in either direction.

```bash
fullsend mint deploy --project="$GCP_PROJECT" --pem-dir=/path/to/pems --public
```

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

### Status Endpoint OIDC Response

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/infrastructure-reference.md

Example JSON response from GET /v1/status when authenticated via OIDC. Scoped to the authenticating workflow's org, includes org, roles, workflow_host_repos, version, and commit.

```json
{"org": "my-org", "roles": ["coder", "review", "triage"], "workflow_host_repos": ["fullsend-ai/fullsend"], "version": "2.0.0", "commit": "abc123"}
```

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

### Workflow permissions for OIDC mode

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/user/inference-gateway.md

Required permissions block for the job running the agent in OIDC mode. Must include `id-token: write` to mint tokens. The `fullsend github setup` installs grants this on its `dispatch` job.

```yaml
    permissions:
      actions: write
      id-token: write
```

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

### Go test suite with behaviourtest.RunPlaybackSuite

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/dev/behaviour-testing.md

Entry point for the dummy-playback suite. Built with -tags playback, runs only @playback-tagged scenarios (GODOG_TAGS is not consulted), and installs pool repos with the dummy-playback runtime. In this repo, make playback-test runs it.

```go
//go:build playback

package behaviour_test

import (
    "testing"

    "github.com/fullsend-ai/fullsend/pkg/behaviourtest"
)

func TestPlaybackSuite(t *testing.T) {
    behaviourtest.RunPlaybackSuite(t, behaviourtest.SuiteOptions{
        FeaturePaths: []string{"features"},
        FixturesRoot: "e2e/behaviour", // module-relative
    })
}
```

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

### Correct Timeout() check with context guard

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/contributing/go-code.md

This pattern excludes context errors before checking Timeout(), so only genuine network timeouts (e.g., net/http.Client.Timeout) are retried. See forge.IsTransient for the canonical example.

```go
// CORRECT — context errors are excluded before the Timeout() check.
if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
    return false
}
var te interface{ Timeout() bool }
if errors.As(err, &te) && te.Timeout() {
    return true // only matches genuine network timeouts (e.g. net/http.Client.Timeout)
}
```

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

### Install repos with nested group path using --gitlab-role-token

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/cli/repos.md

Project paths can include nested groups, e.g., `group/subgroup/project`. Use the same personal access token enrollment as the flat group/project example.

```bash
fullsend repos install group/subgroup/project --gitlab-role-token poller=glpat-xxxxxxxxxxxx --gitlab-role-token analyst=glpat-yyyyyyyyyyyy --gitlab-role-token coder=glpat-zzzzzzzzzzzz
```

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

### Composed harness with base and overrides

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/ADRs/0045-forge-portable-harness-schema.md

Example of a thin harness wrapper generated by 'fullsend install' that references a base harness via URL. The child harness overrides slug and model, and merges runner_env with the base.

```yaml
# .fullsend/harness/triage.yaml
base: https://raw.githubusercontent.com/fullsend-ai/agents/<sha>/harness/triage.yaml#sha256=...
```

```yaml
# .fullsend/harness/triage.yaml
base: https://raw.githubusercontent.com/fullsend-ai/fullsend/<sha>/internal/scaffold/fullsend-repo/harness/triage.yaml#sha256=...
slug: my-org-triage          # override slug
model: sonnet                # override model
runner_env:
  CUSTOM_VAR: value          # merged with base runner_env
```

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

### OpenCode triage run output (trimmed)

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/runtimes/opencode.md

Example output from a triage run with OpenCode, showing model and runtime selection, sandbox bootstrapping, skill uploads, bash tool calls, validation, and exit code 0. The agent bash allowlist is recorded but not enforced on OpenCode.

```text
    Model: google-vertex-anthropic/claude-sonnet-4-6@default (from --model flag)
    Runtime: opencode (from --runtime flag)
runtime: selected "opencode" from --runtime flag
  • Bootstrapping sandbox
Skill "github": uploaded to sandbox
Skill "issue-labels": uploaded to sandbox
Agent Bash allowlist (gh, curl, jq) is recorded but not enforced on opencode — ...
→ Iteration 1 of 2
→ Agent: claude-sonnet-4-6@default
  ⚙ bash: gh issue view 1 --repo <owner>/<repo> --json number,title,body,...
  ⚙ bash: gh label list --repo <owner>/<repo> --json name,description --limit 100
  ✓ Validation passed: Validating: output/agent-result.json against .../triage-result.schema.json
    Agent exit code: 0
    Validation: passed
```

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

### Build Fullsend from source with make go-build

Source: https://github.com/fullsend-ai/fullsend/blob/main/CONTRIBUTING.md

Builds the fullsend binary from source. The binary is written to ./bin/fullsend. Prefer `go run ./cmd/fullsend` when working from this checkout, especially for mint-mutating commands, so the CLI matches the branch under edit.

```bash
make go-build
```

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

### Managed configuration manifest example

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/repo-management.md

Shows a full manifest with defaults, GitHub and GitLab sections. Repositories inherit defaults.config then forge config; repository config overrides. A repository without config gets a sparse managed file with only the ownership marker. An explicit empty allowed_remote_resources list denies all remote resources.

```yaml
version: 1
defaults:
  config:
    runtime: pi
    kill_switch: false
    inference:
      region: us-east1
github:
  config:
    allowed_remote_resources:     # GitHub repositories only
      - https://example.com/agents/
  repos:
    - name: acme/api              # inherits defaults.config, then github.config
    - name: acme/special
      config:
        kill_switch: true         # repository values win
        allowed_remote_resources: []   # explicit empty list: deny all
    - name: acme/plain            # no config key: still managed (sparse, marker only)
gitlab:
  url: https://gitlab.example.com
  config:
    runtime: claude               # GitLab repositories only
  repos:
    - name: group/project

```

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

### Update GitHub secrets and variables with fullsend github set

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/operations.md

Use `fullsend github set` to update individual secrets or variables without re-running full setup. The command takes the repository as `$OWNER/$REPO`, the key name, and the new value. Example updates `FULLSEND_GCP_PROJECT_ID` and `FULLSEND_GCP_REGION`.

```bash
fullsend github set "$OWNER/$REPO" FULLSEND_GCP_PROJECT_ID new-gcp-project
fullsend github set "$OWNER/$REPO" FULLSEND_GCP_REGION global
```

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

### Create and provision a VM (project-scoped runner)

Source: https://github.com/fullsend-ai/fullsend/blob/main/hack/gitlab-runner-vm/README.md

Creates a VM with a project-scoped runner for single-project deployments. Requires GL_TOKEN, PROJECT_ID, GITLAB_URL, NAMESPACE, and RUNNER_IMAGE.

```bash
GL_TOKEN=glpat-xxx PROJECT_ID=12345 \
  GITLAB_URL=https://gitlab.example.com \
  NAMESPACE=my-namespace \
  RUNNER_IMAGE=ghcr.io/org/runner:v1.2.3 \
  ./create-openshift-vm.sh
```

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

### Add multiple repos and preview

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/getting-started/repo-management.md

Adds two repos and runs a dry-run install to preview changes without applying them.

```bash
fullsend repos set 'github.repos["acme/new-api"]' '{}'
fullsend repos set 'github.repos["acme/new-web"]' '{}'
fullsend repos install acme/new-api acme/new-web --dry-run
```

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

### Example: standalone only (no fallback)

Source: https://github.com/fullsend-ai/fullsend/blob/main/docs/guides/infrastructure/standalone-mint.md

Configures the standalone mint without a fallback. Requests for roles without local PEMs will be rejected.

```bash
export PER_REPO_WIF_REPOS="myorg/my-repo"
export ROLE_APP_IDS='{"triage":"4087047","scanner":"5555555"}'
export PEM_DIR="./pems"
export ALLOWED_WORKFLOW_FILES="*"
export CUSTOM_ROLE_PERMISSIONS='{"scanner":{"contents":"read","security_events":"write","metadata":"read"}}'

./fullsend-mint
```
Tokens:
Raw