Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.whim.run/llms.txt

Use this file to discover all available pages before exploring further.

Workspace images let you build custom container runtimes with your project’s dependencies pre-installed. Instead of installing tools on every task startup, bake them into an image once and every new task launches ready to go. There are two workflows: manual (paste a Dockerfile in settings) and repo-managed (commit a Dockerfile in your repo and let Whim rebuild automatically on branch changes).

Manual

Paste a Dockerfile into Settings > Images. Best for simple, project-wide customizations.

Repo-managed

Add config to whim.json or package.json, commit a Dockerfile, and Whim builds branch-specific images automatically.

​
Manual setup

1

Create a new image

Navigate to Workspace Settings > Images and click New Image. Paste a full Dockerfile.
2

Watch the build

Builds run remotely. If something fails, check the Build Log tab.
3

Activation

Builds started from Settings > Images auto-activate after they pass runtime compatibility validation. If you start a build through the API or agent tooling without auto-activation, activate the ready image manually.
ARG RUNNER_COMPAT_REF
FROM ${RUNNER_COMPAT_REF}

USER root
RUN apt-get update && apt-get install -y git ripgrep
RUN python3 -m pip install --no-cache-dir poetry ruff
USER node
Manual builds use a Dockerfile-only context — no local files. Use inline heredoc COPY/ADD or COPY --from=... from earlier stages.

​
Repo-managed setup

Add image configuration to your repository root. Whim checks whim.json first, then falls back to the whim.image field in package.json.
whim.json
{
  "image": {
    "dockerfile": "Dockerfile.whim",
    "context": ".",
    "stagedFiles": ["package.json", "pnpm-lock.yaml"],
    "buildSecrets": ["NPM_TOKEN"]
  }
}
FieldDescription
dockerfilePath to the Dockerfile relative to repo root
contextBuild context directory (usually ".")
stagedFilesFiles available for COPY/ADD during build
buildSecretsWorkspace env var names exposed as build secrets. GITHUB_TOKEN is platform-managed for repo-managed builds — only list additional secrets like NPM_TOKEN.
Dockerfile.whim
ARG RUNNER_COMPAT_REF
FROM ${RUNNER_COMPAT_REF}

COPY package.json pnpm-lock.yaml /app/
RUN cd /app && pnpm install --frozen-lockfile

USER root
RUN python3 -m pip install --no-cache-dir poetry ruff
USER node
After committing the config and Dockerfile, go to Settings > Images and track the branch. The default branch is tracked automatically; non-default branches must be explicitly tracked.

​
Dockerfile rules

These apply to both manual and repo-managed Dockerfiles:
  • Must start with ARG RUNNER_COMPAT_REF and the final stage must use FROM ${RUNNER_COMPAT_REF}. Whim resolves this to the workspace-compatible runner image at build time.
  • Repo-managed builds can only COPY/ADD files listed in stagedFiles.
  • Image freshness is determined by hashing the normalized config, Dockerfile content, and stagedFiles contents — not the entire repo.
  • Multi-stage builds work as long as you use COPY --from=... between stages.
  • Build secrets referenced in buildSecrets must exist as workspace environment variables. For repo-managed builds, GITHUB_TOKEN is automatically provided by the platform — you don’t need to list it or set it as an env var.

​
Build status

StatusDescription
BuildingDocker build running remotely
ReadyBuild succeeded, available for activation
FailedBuild failed — check the build log
After a successful build, Whim validates runtime compatibility. An image must be both Ready and Compatible before activation.

​
Activating images

Only one image can be active per workspace (or per tracked branch for repo-managed workflows).
  • Activate — sets the image as active and triggers warm reserve pool rebuild. Only Ready + Compatible images can be activated.
  • Deactivate — removes the active image. Tasks fall back to the default Whim runtime.
Only team admins can build, activate, delete, or track workspace images.

​
Warm reserves

Warm reserves are pre-created, suspended machines running your custom image. When a task starts, Whim claims a reserve and resumes it instantly instead of building a new container.

​
How it works

  1. Whim creates machines with your image and initializes them
  2. Machines are suspended — no compute cost, but ready to go
  3. When a task starts, Whim claims an available machine, resumes it, and injects the task config
  4. If no reserve is available, Whim falls back to creating a new container (slower startup)

​
Reserve targets

Each tracked branch has a reserve target (0–20 machines). Default branch reserves are included in your plan:
PlanIncluded reserves
Free3 machines
Pro5 machines
Max10 machines
Machines above the included amount, and all non-default branch reserves, cost 3 CU per week each (prorated).
Warm starts are best-effort. Even with reserves configured, the pool can be empty. Whim falls back to creating a new container if needed.

​
Branch tracking

For repo-managed workflows, branch tracking controls which branches get dedicated images and warm reserves.
  • Default branch — automatically tracked, uses plan-included reserve capacity.
  • Non-default branches — must be explicitly tracked from Settings > Images. Reserve machines consume CU.
  • Fallback — if a tracked branch’s image isn’t ready yet, tasks may launch with a similar image or the default runtime.
  • Stale cleanup — branches with no task activity for 14 days are automatically untracked.

​
Agent workflow

Inside Whim task containers, agents can help create and update workspace images.
  • The built-in workspace-image-builder skill can inspect the repo, draft a compliant Dockerfile, and update existing image definitions.
  • For manual images, agents can use the built-in images MCP tool to list images, start a build from a full Dockerfile, fetch build logs, activate ready images, and delete old images.
  • Repo-managed image work still happens as repo changes: update whim.json or package.json, edit the Dockerfile in git, commit the changes, then track the branch from Settings > Images if it is not already tracked.

​
Baked repository

The baked-repo optimization pre-clones your repository into the workspace image at build time. When a task starts, Whim runs a fast git fetch to freshen the clone instead of doing a full clone from scratch — significantly faster startup for large repos.

​
How it works

Use RUN --mount=type=secret,id=GITHUB_TOKEN in your Dockerfile to clone the repo during the build:
Dockerfile.whim
ARG RUNNER_COMPAT_REF
FROM ${RUNNER_COMPAT_REF}

RUN --mount=type=secret,id=GITHUB_TOKEN \
    git clone https://x-access-token:$(cat /run/secrets/GITHUB_TOKEN)@github.com/your-org/your-repo /home/node/repo
For repo-managed builds, Whim automatically injects GITHUB_TOKEN using its GitHub App installation — no personal access tokens or workspace environment variables needed. At task startup, the pre-cloned repo is freshened with git fetch rather than cloned from scratch.
Baked-repo builds only work with repo-managed setups. Whim needs GitHub App access to the repository to inject the token at build time.

​
Overriding the token

If you need to access a different repository than the one connected to the workspace, declare GITHUB_TOKEN in buildSecrets and set it as a workspace environment variable. A user-supplied value takes precedence over the auto-injected platform token.

​
Mixing workflows

Manual and repo-managed images can coexist, but behavior is easier to reason about if you standardize on one.