Documentation Grafana Cloud Platform Assistant Configure Sandbox images

Customize sandbox tools with a Dockerfile

Grafana Assistant can prepare a custom image for your repository’s coding sandboxes. Add a Dockerfile to install the tools and dependencies your project needs. Without a Dockerfile, Assistant uses the default Alpine Linux 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 and use Grafana sandbox. Connect your repositories and turn on Managed Sandboxes for the repository.

You need permission to merge the Dockerfile into the repository’s default branch. To refresh images or view build logs, you need Assistant Coding Admin, or Assistant Coding Maintainer with a linked GitHub account that has current write access to the repository.

Add a Dockerfile

Ask Assistant to prepare the Dockerfile, or write it yourself. In either case, merge it into the default branch before refreshing the image.

Ask Assistant to prepare the Dockerfile

In an Assistant conversation, ask it to set up a sandbox environment for your repository. Assistant inspects the project and proposes a pull request with .grafana/Dockerfile. Review and merge the PR, then follow Check or refresh your environment.

Write the Dockerfile yourself

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 GRAFANA_BASE_IMAGE. 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.

If you use your own base image instead, choose Linux ARM64 and install Bash, Git, GNU grep, tar, and base64. Make /workspace/repo writable.

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 AI > Settings > Managed Sandboxes > 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 use the default image. Custom network settings and repository secrets remain. To remove those too, open the repository’s environment and click Delete environment after the image returns to the default.

To stop builds completely, set Managed Sandboxes to Off for the repository in AI > Settings > Connectors > GitHub. A build that’s already running then doesn’t replace the current image.

Next steps

Refer to Use Grafana Managed Sandboxes to configure repository network access and secrets, start coding tasks, and review changes.