---
title: "Customize sandbox tools with a Dockerfile | Grafana Cloud documentation"
description: "Install tools and dependencies for Grafana Assistant coding sandboxes with a repository Dockerfile."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Customize sandbox tools with a Dockerfile

> Note
> 
> Custom sandbox images is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```dockerfile
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```dockerfile
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.