> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darkbloom.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CI quickstart

> Connect a public GitHub repository to Darkbloom, route a workflow to Linux or macOS runners, and watch the first job run.

This page takes you from a Darkbloom account to a GitHub Actions job running on
a Darkbloom Linux or macOS runner. For the full lane and fallback reference,
see [route workflows](https://docs.darkbloom.dev/ci/route-workflows.md).

## Before you start

* **A Darkbloom account with funds.** Jobs draw on the same balance as
  Darkbloom inference.
* **A public repository.** Darkbloom runs public repositories only. Private
  repositories cannot be requested.
* **Administration of the GitHub account or organization** that owns the
  repository, so you can install the App and pick its repositories.

## Sign in

Open [https://api-sandbox.darkbloom.dev](https://api-sandbox.darkbloom.dev) and
sign in with your Darkbloom account.

## Install the GitHub App and link it for billing

1. On **GitHub**, choose **Connect GitHub**.
2. GitHub asks you to install the **Darkbloom Sandbox** App on your account or
   on an organization you administer, to pick repositories (public ones:
   Darkbloom runs nothing else), and to authorize the App.
3. GitHub returns you to the console. The console checks that you control the
   installation, records your consent to pay for its jobs, and links it to your
   account. The page lists the installation with its repositories.

If GitHub returns without linking (for example because the App was installed
from GitHub directly), remove the installation on GitHub and connect again from
the console.

Each installation is billed to one Darkbloom account. **Disconnect** stops new
jobs and revokes your consent; running jobs finish and are charged.

## Add funds

Jobs are paid from your Darkbloom balance, the same one Darkbloom inference
uses. Add funds in the Darkbloom console. A job that cannot be paid for is not
started.

## Set spend limits

Choose **Edit limits** on the installation:

* **Concurrent jobs** (1 to 100, default 2): more jobs wait for a free slot.
* **Monthly cap** (optional, in US dollars per calendar month, UTC): settled
  charges plus open holds. Lanes that would not fit fall back to your runners
  (`monthly_spend_cap`); the card shows spend this month against the cap.

![Sandbox console GitHub page showing a linked installation, spend against its monthly cap, concurrent jobs and repository access](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/ci-github.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=926c6a2ffd77a393ec0f605ee668293a)

The GitHub page in the sandbox console: a linked installation with its repositories, spend this month, monthly cap and concurrent jobs. Example data.

## Request access for a repository

Each public repository on the **GitHub** page has **Request access**. A
Darkbloom operator reviews it and approves or denies it; the console shows the
decision:

| Status | Meaning |
| - | - |
| Access requested | Waiting for an operator. Lanes fall back as `repository_not_approved` |
| Approved | Which profiles, events (pull requests, pushes to named branches) and lanes may run on Darkbloom, and until when (at most 90 days) |
| Denied | The operator's reason. Fix it and **Request again** |
| Approval expired | Lanes fall back until it is renewed: **Request renewal** |

Private repositories show *Private* and cannot be requested.

Tell your Darkbloom contact which hosts beyond GitHub your jobs download from
(package registries, model hubs): only reviewed hosts are reachable. See
[caching and network](https://docs.darkbloom.dev/ci/caching-and-network.md).

## Add the route workflow

1. Copy `route.yml` from the Darkbloom actions repository at a commit into your
   repository as `.github/workflows/darkbloom-route.yml`, unchanged. Call it
   locally: Darkbloom refuses the jobs of a workflow that calls a reusable
   workflow from another repository.
2. Start the workflow with a `route` job and take each routed job's `runs-on`
   from it:

   ```yaml theme={null}
   permissions:
     contents: read

   jobs:
     route:
       uses: ./.github/workflows/darkbloom-route.yml
       permissions: {}
       with:
         lanes: |
           test linux_arm64 ubuntu-24.04-arm 2
           macos macos_arm64 macos-15

     test:
       needs: route
       runs-on: ${{ fromJSON(needs.route.outputs.routes)['test'] }}
       strategy:
         matrix:
           shard: [1, 2]
       steps:
         - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
           with:
             persist-credentials: false
         - run: make test SHARD=${{ matrix.shard }}
   ```

   Each lane line is `<lane> <profile> <fallback-label> [count]`: `count` is
   how many jobs the lane runs (its matrix size, at most 16). Keep the `route`
   job's `permissions: {}`: the route workflow's job holds exactly what its
   calling job grants, so it then holds no token permission.
3. Set the repository variable `DARKBLOOM_ROUTING` to `on` (**Settings →
   Secrets and variables → Actions → Variables**). Any other value keeps every
   lane on its fallback.

Jobs that may run on Darkbloom must:

* declare read-only token permissions (`read` or `none`) on the job or the
  workflow;
* use no secrets (none in the job, the workflow's `env` or the local actions
  and reusable workflows it uses), no `environment`, `services`, `container`
  or container actions;
* not share a workflow with a call to another repository's reusable workflow.

Keep release, publishing and deployment jobs on your own runners. Pull
requests from forks keep their fallback runners.

### Add the watchdog workflow

A lane routed to Darkbloom can only run on a Darkbloom runner. So that a run
never waits for one for hours (Darkbloom down, its service unreachable), also
copy `watchdog.yml` from the same commit into your repository as
`.github/workflows/darkbloom-watchdog.yml`, unchanged.

Every 10 minutes, with your repository's own `GITHUB_TOKEN` (`actions: write`
and `checks: write`, which it declares), it cancels a run whose Darkbloom job
has waited queued with no runner for 30 minutes since it was created while no
Darkbloom job of the run got a runner, also when other Darkbloom jobs of the
run ran, and re-runs its route job: the new attempt's lanes fall back. It
rescues a run at most once, never re-runs a run someone else cancelled, and
leaves a run alone while Darkbloom's own watchdog is rescuing it (a `Darkbloom
watchdog` check on the commit).

It cannot tell a job that waits at your concurrency or resource limit from a
fault: raise `DARKBLOOM_WATCHDOG_MINUTES` above such waits. Repository
variables: `DARKBLOOM_WATCHDOG` `off` turns it off; `DARKBLOOM_WATCHDOG_MINUTES`
(15 to 1440) changes the wait; `DARKBLOOM_ROUTE_JOB` names your route job when
it is not the workflow's `Select Runners`. Re-running repeats what your jobs do,
so add it only where that is safe (CI checks, not deployments).

## See the job run

* **The route job's summary** in each run lists every lane's runner and why.
* **Runs** lists your Darkbloom jobs: state, outcome, runner class, charge
  (held, settled or released, with the reason) and integrity; each links to its
  GitHub job. The detail shows the timeline from queued to finished.
* **Billing** shows your balance, each charge (rate, hold, billable seconds,
  cost) and the rates.
* **Receipts**: the Mac that ran a job signs a receipt for it, which Darkbloom
  verifies. *Verified* means the Mac's attested add-on signed it; *Unverified*
  means it could not be checked (the run's result still stands). The commit
  also gets a **Darkbloom sandbox integrity** check.

![Sandbox console Runs page listing jobs with status, runner, host, duration, cost and integrity](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/ci-runs.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=8f7fbe5009ab53e83a1d4d7cad3b7929)

The Runs page in the sandbox console: each job's state, runner, charge and integrity. Example data.

If a lane stays on its fallback, the route job's summary says why; the reasons
are in [troubleshooting](https://docs.darkbloom.dev/ci/troubleshooting.md).

![Sandbox console run detail showing the timeline from queued to finished, the charge and the integrity check](https://mintcdn.com/eigenlabs-f49d2e97/2TtlNanikOmTAJr5/images/console/ci-run-detail.png?fit=max\&auto=format\&n=2TtlNanikOmTAJr5\&q=85\&s=e85bf3a1f9ce59b2e8cd1116fe39f797)

A run's page in the sandbox console: its timeline from queued to finished, charge and integrity. Example data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.