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 your repository to install the tools and dependencies your project needs. Without a Dockerfile, Assistant uses an Alpine-based default image with Git, GitHub CLI (gh), curl, jq, CA certificates, uv, and Python already installed.

Before you begin

Before you add a custom image, make sure you have the following:

• Custom sandbox images enabled for your Grafana Cloud stack.
• The GitHub App connected, with Cloud agents set to Auto-publish PRs or Ask before publishing for your repository in Assistant > Settings > Connectors > GitHub. Assistant builds images only for these repositories.
• Write access to the repository’s default branch, so you can change its environment.
• To refresh the image or view build logs, the grafana-assistant-app.github:write permission, included in Assistant Coding Admin, or the Assistant Coding Maintainer role plus write access to the repository through your linked GitHub account.

Add a Dockerfile

Ask Assistant to set up a sandbox environment for the repository. 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, click Refresh on the repository’s environment to build the image now. For details, refer to Check or refresh your environment.

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. You can use any base image, and GRAFANA_BASE_IMAGE is optional. Builds run with Buildah in a disposable sandbox, so Dockerfile support follows Buildah, including ADD, ONBUILD, and COPY --from with external images. The resulting image needs Bash, Git, GNU grep, tar, and base64, with a writable /workspace/repo.

Public dependency downloads are allowed. Builds can’t use 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.

Each build must finish within 5 minutes and can use up to 16 MiB of source files, 4 GiB for downloaded images and layers, and 2 GiB of memory. The Dockerfile can be up to 256 KiB and 4,096 lines. Build logs can be up to 1 MiB and are kept for seven days.

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 can’t push changes or create pull requests or issues. Assistant publishes completed changes separately, following the repository’s pull request policy. Build steps don’t get this GitHub access.

Check or refresh your environment

On Assistant > Settings > Cloud agents > Environments, a repository with a custom image has its own environment. Click Edit to see its latest build status, and click Refresh to rebuild the image. Expand Build logs to see the output. While a replacement builds, new sandboxes use the previous successful image. Before the first successful build, they use the default image. Existing sandboxes keep their current files and environment.

Assistant checks the default branch when you save the repository and then daily. It rebuilds when any file in .grafana/ changes, including the Dockerfile and .dockerignore. It also rebuilds when Grafana updates the base image you reference through GRAFANA_BASE_IMAGE. Updates to other base image tags, for example, alpine:latest, don’t trigger a rebuild. Application code changes don’t trigger one either, because each new sandbox fetches your code when it starts.

Click Refresh to check immediately and build without cached layers, even if nothing in .grafana/ has changed. Refresh also pulls current base image tags, so use it when a base image or downloaded dependency has changed. Age alone doesn’t make a successful image stale. If a build fails, fix the Dockerfile or installation files and click Refresh. Assistant doesn’t retry a failed build daily unless its files change.

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. To stop builds completely, set Cloud agents to Off for the repository in Assistant > Settings > Connectors > GitHub. A build that’s already running then doesn’t replace the current image.