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

# Advanced: custom setup

> Start every CI job from a machine you prepared once, with your toolchain, dependency caches, and service images already in place.

Prepare a machine once with everything your jobs need, save it as a snapshot, and start every job
from a copy of it.

## Why

A job on a fresh machine repeats the same setup before it runs a single test: it installs your
toolchain, restores dependency caches, and pulls the images of the services it tests against. With a
snapshot, that setup runs once.

* **Each job starts with the setup on disk**, so its time goes to your build and tests.
* **Each job gets its own copy**, so jobs stay isolated from each other, as on a fresh machine.
* **Fewer downloads in every job**, so fewer jobs fail on a registry or a mirror that is slow or
  down, and less cache traffic.

## Set it up

You need the GitHub App connected ([Run CI jobs on fresh machines](https://instabox.sh/docs/use-cases/ci)), a paid plan,
and a private repository with **Run workflows from fork pull requests** turned off.

**1. Create a CI machine**

Create a machine from the `ci` template. A job only starts from a snapshot of a `ci` machine.

```bash theme={null}
instabox create --name ci-warm --template ci
```

**2. Open a shell in it**

```bash theme={null}
instabox ssh ci-warm
```

**3. Clone your repository**

In that shell, clone the repository to `~/work/<repo>/<repo>`, which is where `actions/checkout`
puts it. A job's checkout then only fetches what changed. `acme/app` stands for your repository
on this page.

```bash theme={null}
git clone https://github.com/acme/app ~/work/app/app
```

**4. Install what your jobs install**

Run the setup that your workflow runs before its tests, so that the results are on the disk. For
a Node.js project, that is the dependency install.

```bash theme={null}
cd ~/work/app/app && npm ci
```

Pull the images of the services that your tests start.

```bash theme={null}
docker pull postgres:16
```

Then leave the shell.

```bash theme={null}
exit
```

**5. Stop the machine**

Stop the machine before you save it, so that everything your setup wrote is on its disks.

```bash theme={null}
instabox stop ci-warm
```

**6. Save the snapshot**

Save the snapshot under a name that you can use in a label. The command returns when the
snapshot is ready.

```bash theme={null}
instabox snapshot save ci-warm --name acme-warm
```

**7. Point your jobs at the snapshot**

In your workflow, add `-snapshot-` and the snapshot's name to the size label. The label is the
job's whole `runs-on`.

```yaml theme={null}
jobs:
  test:
    runs-on: instabox-medium-snapshot-acme-warm
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
```

Keep the setup steps in the workflow. They finish fast when the snapshot already has their
results, and they still do the work when a dependency changed after you saved the snapshot.

**8. Check that a job used the snapshot**

Push a commit, and list your jobs. The `SNAPSHOT` column has the snapshot's name for a job that
started from it.

```bash theme={null}
instabox ci
```

```text theme={null}
ID    REPO      JOB        SIZE             SNAPSHOT   STATE               WAIT  RUN  REASON
1042  acme/app  CI / test  instabox-medium  acme-warm  running             9s    41s
1041  acme/app  CI / lint  instabox-medium  -          completed: success  12s   1m
```

## Examples

Each example lists what to run in the machine before you save it, and the label that the jobs use.
The commands stand for your own project's setup.

> [tab] Node.js monorepo
>
> A TypeScript monorepo with end-to-end tests installs thousands of packages and downloads
> browsers in every job. Put `node_modules` and the Playwright browsers in the snapshot.
>
> ```bash theme={null}
> cd ~/work/web/web && npm ci
> ```
>
> ```bash theme={null}
> npx playwright install --with-deps chromium
> ```
>
> ```yaml theme={null}
> runs-on: instabox-large-snapshot-web-warm
> ```

> [tab] Go service with databases
>
> A Go service with integration tests downloads its modules, compiles its dependencies, and pulls
> Postgres and Redis in every job. Put the module cache, the build cache, and both images in the
> snapshot.
>
> ```bash theme={null}
> cd ~/work/api/api && go mod download
> ```
>
> ```bash theme={null}
> go build ./... && go vet ./...
> ```
>
> ```bash theme={null}
> docker pull postgres:16
> ```
>
> ```bash theme={null}
> docker pull redis:7
> ```
>
> ```yaml theme={null}
> runs-on: instabox-medium-snapshot-api-warm
> ```

> [tab] Python ML repository
>
> A Python repository for model code installs large packages and downloads a model or a dataset in
> every job. Put the installed packages and the download in the snapshot. `scripts/fetch_model.py`
> stands for your own download step.
>
> ```bash theme={null}
> cd ~/work/ml/ml && pip install -r requirements.txt
> ```
>
> ```bash theme={null}
> python scripts/fetch_model.py
> ```
>
> ```yaml theme={null}
> runs-on: instabox-xlarge-snapshot-ml-warm
> ```

## When not to use it

* **A small repository** whose setup takes a few seconds. A fresh machine is simpler, and there is
  no snapshot to keep up to date.
* **A workflow that changes its dependencies on every run**, such as one that always installs the
  latest versions. The snapshot's copies are out of date at once, so each job downloads them again.

## Refresh the snapshot

Save the snapshot again when your dependencies change enough that jobs install much of them again,
and at least once a month. A snapshot keeps the GitHub Actions runner that it was saved with, and
GitHub stops sending jobs to a runner that is more than 30 days behind its latest release.

A snapshot's name cannot be used again while that snapshot exists, so save the new one under a new
name.

```bash theme={null}
instabox snapshot save ci-warm --name acme-warm-2
```

Change `runs-on` to the new label, and delete the old snapshot when no workflow names it.

```bash theme={null}
instabox snapshot rm acme-warm
```

## What to know

* **Each job gets its own copy.** A job cannot change the snapshot, so nothing that one job writes
  reaches another job.
* **Keep secrets out of the snapshot.** Any workflow on a branch of a linked repository can name
  the snapshot and read what is in it. Jobs get their secrets from GitHub Actions as usual.
* **The size is the snapshot's.** Name the size label of the machine that you saved, such as
  `instabox-medium-snapshot-` for a snapshot of an `instabox-medium` machine. You can also name the
  snapshot by its ID, as in `instabox-medium-snapshot-sn_...`.
* **Stop services before you save.** Stop any service that you started in the machine, so that the
  snapshot holds files and not half-written data.
* **A job from a snapshot waits for its machine to start.** Machines for the plain size labels are
  started ahead of jobs, and machines from your snapshot are not.
* **Refreshing is a manual step today.** Save the snapshot again yourself when it is due.
* **A job that names a snapshot is never moved to a fresh machine.** When the snapshot is missing,
  still saving, or not from a `ci` machine, the job is refused, and `instabox ci` shows the reason.
  See [When a job that names a snapshot is refused](https://instabox.sh/docs/use-cases/ci#when-a-job-that-names-a-snapshot-is-refused).

> [card] [Run CI jobs on fresh machines](https://instabox.sh/docs/use-cases/ci)
>
> Connect GitHub, size labels, and what the machine has installed.

> [card] [Snapshots](https://instabox.sh/docs/machines/snapshots.md)
>
> Save, list, and delete snapshots.
