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, GitHub CLI (gh), 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 turn on your repository in Assistant > Settings > External connections > GitHub. 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

Open Assistant > Settings > Coding agents, select the Repositories tab, and select Set up with Assistant next to a repository using the default image. Assistant inspects the project and prepares a .grafana/Dockerfile with its development tools, then proposes a pull request through the normal publishing flow. After you merge it, select Refresh to build the image.

To configure it yourself, create .grafana/Dockerfile on your repository’s default branch. Extend Grafana’s base image to keep the preinstalled tools and add your own:

dockerfile Copy

ARG GRAFANA_BASE_IMAGE
FROM ${GRAFANA_BASE_IMAGE}

RUN apk add --no-cache nodejs npm ripgrep

Grafana supplies the configured base image digest through GRAFANA_BASE_IMAGE. You don’t need to manage the image URL or digest. Replace the packages with the ones your project needs.

For a setup script, add these instructions and place the script at .grafana/setup.sh:

dockerfile Copy

COPY setup.sh /tmp/setup.sh
RUN sh /tmp/setup.sh && rm /tmp/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.

You can also choose your own base image and install the required tools yourself:

dockerfile Copy

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

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 Bash, Git, GNU grep, 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.

In a running sandbox, gh uses the existing GitHub connection to read the selected repository’s contents, pull requests, and issues. For example, use gh pr list or gh issue view 123 from the repository directory. Sandbox commands cannot push changes or create pull requests or issues; Assistant publishes completed changes separately according to the repository’s pull request policy. Build steps do not receive this GitHub access.

Check or refresh your environment

The repository row on the Repositories tab 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. Turning the repository off in Assistant’s GitHub settings prevents further builds and promotion of pending results.