Documentation Grafana Cloud Platform Assistant Configure Sandbox images

Customize sandbox tools with a Dockerfile

Grafana Assistant can prepare a custom environment for your repository’s coding sandboxes. Add a Dockerfile to install the tools and dependencies your project needs. Without a Dockerfile, Assistant uses the Alpine-based Wingbox guest image with Git, curl, jq, CA certificates, uv, and Python already installed.

Before you begin

Your Grafana Cloud stack must have custom sandbox images enabled. Connect the GitHub App and save your repository in Assistant’s GitHub settings. You need write access to the repository’s default branch to change its environment and the GitHub settings write permission to request a refresh.

Add a Dockerfile

Create .grafana/Dockerfile on your repository’s default branch. Choose any base image:

dockerfile Copy

FROM alpine:latest
RUN apk add --no-cache git ca-certificates

# Add your installation commands here.
COPY setup.sh /tmp/setup.sh
RUN sh /tmp/setup.sh && rm /tmp/setup.sh

Place the installation script at .grafana/setup.sh. Paths in COPY are relative to .grafana/. Application files and root-level lockfiles aren’t available during the build. Put any installation manifests you need inside .grafana/ as well. Use .grafana/.dockerignore to exclude unnecessary files.

To extend the preinstalled Grafana tools, use:

dockerfile Copy

ARG GRAFANA_BASE_IMAGE
FROM ${GRAFANA_BASE_IMAGE}
RUN apk add --no-cache make

The environment targets Linux ARM64. There is no base-image allowlist and GRAFANA_BASE_IMAGE is optional. Podman resolves base images and executes the Dockerfile inside a disposable build VM, including ADD, ONBUILD, and external COPY --from sources. Dockerfile syntax support follows Podman. The resulting image needs a shell, Git, tar, and base64, with a writable /workspace/repo.

Public dependency downloads are allowed. Builds cannot use customer secrets, private registries, private network services, or authenticated package downloads. Don’t place credentials in the Dockerfile or build context: they can become part of the image or its logs.

Check or refresh your environment

The repository row in GitHub settings shows the active environment and the latest build status. Expand View logs for build output. While a replacement builds, new sandboxes use the previous successful image. Before the first successful build, they use the default image. Existing sandboxes retain their current files and environment.

Assistant checks the default branch when you save the repository and then daily. It rebuilds when the effective .grafana/ contents, Dockerfile, ignore rules, or the Grafana base changes when referenced through GRAFANA_BASE_IMAGE. Changes to other remote base tags alone don’t trigger a rebuild. Ordinary application-code changes don’t trigger an image rebuild. Application code is fetched separately when a new sandbox starts.

Click Refresh to check immediately and build without cached layers, even if those inputs haven’t changed. Refresh also pulls current base tags, so use it when a base image or downloaded dependency has changed. An older successful image remains usable; age alone doesn’t make it stale. If a build fails, correct the Dockerfile or installation files and click Refresh. Unchanged failed inputs aren’t automatically rebuilt every day.

Builds have a 30-minute deadline, a 16 MiB source limit, 4 GiB for downloaded images and layer storage, and 2 GiB of build memory. The Dockerfile is limited to 256 KiB and 4,096 lines. Logs are limited to 1 MiB and retained for seven days.

Restore the default environment

Remove .grafana/Dockerfile from the default branch, then click Refresh or wait for the daily check. New sandboxes return to the default environment. Removing the repository from GitHub settings prevents further builds and promotion of pending results.