---
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 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](/docs/grafana-cloud/platform/grafana-assistant/platform/cloud-agents/#connect-your-repositories) and turn on **Cloud agents** 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](#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 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 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```dockerfile
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](/docs/grafana-cloud/platform/grafana-assistant/platform/cloud-agents/#review-and-publish-changes). Build steps don’t get this GitHub access.

## Check or refresh your environment

On **AI** > **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 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 **Cloud agents** 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 Cloud Agents](/docs/grafana-cloud/platform/grafana-assistant/platform/cloud-agents) to configure repository network access and secrets, start coding tasks, and review changes.