Use Grafana Managed Sandboxes
Note
Grafana Managed Sandboxes is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
Use Managed Sandboxes to ask questions about source code, make changes, and prepare pull requests from your conversations in Grafana Cloud. You can give an agent context from your metrics, logs, traces, and profiles to help it diagnose a problem and propose a fix.
Before you begin
Make sure you have the following:
- A Grafana Cloud stack with Grafana Assistant and Managed Sandboxes enabled.
- Assistant Coding User permission to run agents.
- An Assistant Coding Admin who can configure the provider and GitHub connection.
- Permission to install or approve the Grafana Assistant GitHub App for the repositories you want to use.
Assistant Coding Maintainer lets you manage repositories you can write to on GitHub. For role assignments, refer to Control Managed Sandboxes access.
Link your personal GitHub account when Assistant prompts you. You need GitHub read access to inspect connected repositories and write access to publish changes. Installing the GitHub App doesn’t replace this link. Read-only discovery of public repositories can run without linking, but can’t publish changes.
Set up Managed Sandboxes
Enable a provider, then connect its repositories. If your administrator has already completed setup, continue to Ask an agent to work on code.
Configure Managed Sandboxes
Choose one active provider before selecting repositories. Grafana Cloud uses the repositories you connect in GitHub settings.
- Open AI > Settings > Managed Sandboxes.
- Select Grafana Cloud.
- In the Status row, click Enable.
The Overview tab shows how many repositories can use Managed Sandboxes and how they publish, which repositories have restricted network access, and which global secrets the agent can read. Click a row to open the place where you manage it. To stop new tasks without deleting repository or secret settings, click Disable in the Status row.
Depending on your preview access, Cursor and Claude appear under Hand off to. Instead of starting a Grafana sandbox, Assistant writes the task and sends it to the provider, which works in its own cloud with its own repository access. Environments, secrets, and network rules don’t apply, and Grafana can’t review changes before they reach GitHub. To hand off tasks, select the provider, save its API key, click Enable, and confirm. Cursor reaches the repositories its own GitHub integration allows. Claude works on the repositories you turn on in GitHub settings.
Connect your repositories
Choose which repositories Assistant can access before you use Managed Sandboxes to change code. The GitHub connection is shared by every Assistant feature that works with GitHub, so you connect it once.
To connect GitHub, you need the grafana-assistant-app.github:write permission, included in Assistant Coding Admin.
- Open AI > Settings > Connectors > GitHub.
- Click Install GitHub App. In the GitHub window that opens, authorize your GitHub account if prompted. The window then continues to the app installation.
- Complete the GitHub App installation for your account or organization, and grant the app access to the repositories you want to use.
- Return to Assistant’s GitHub settings and, on the Repositories tab, turn on the features each repository can use.
If the GitHub App is already installed on an account or organization that your linked GitHub account owns, for example, for another Grafana Cloud stack, you don’t need to install it again. Find the account under Already installed on these GitHub organizations or accounts and click Connect. After you connect it, Install GitHub App changes to Manage on GitHub, which opens the installation’s settings on GitHub.
Each repository row has a control for every feature that can use it:
- @grafana mentions starts Assistant sessions when someone tags
@grafanain an issue or pull request. - Change review reviews pull requests to the default branch, when change review is available for your stack.
- Managed Sandboxes sets whether Managed Sandboxes can work in the repository. It appears when Grafana Cloud or Claude Managed Agents is the active provider. For Grafana Cloud, choose Off, Ask before publishing, Auto-publish draft PRs, or Auto-publish ready PRs. For Claude, turn the switch on or off.
Use the All repositories row to set a feature for every repository at once. For Grafana Cloud, Set all applies one of these choices to every repository. Public repositories can’t auto-publish. Changes save as you make them. A repository with every feature turned off loses Assistant access.
If Cursor Cloud is the active provider, it gets repository access from your Cursor account instead of this list. If a repository isn’t available, check that the GitHub App installation includes it, then click Refresh repositories.
Ask an agent to work on code
In an Assistant conversation, describe the repository, the task, and the result you want. Include relevant errors or investigation findings, for example, a failing request and the logs that show it.
Start with a read-only question:
Use Managed Sandboxes to inspect <REPOSITORY_OWNER>/<REPOSITORY_NAME> and explain how it handles request timeouts. Don't change any files.When you’re ready to make a change, describe the expected behavior:
Use Managed Sandboxes to update <REPOSITORY_OWNER>/<REPOSITORY_NAME> so timed-out requests return a clear error. Add a regression test and summarize the changes and test results.Replace REPOSITORY_OWNER and REPOSITORY_NAME with your GitHub repository owner and name. Respond to any approval request to let the task proceed. You can send follow-up instructions in the same conversation to refine the work.
Review and publish changes
Open Changes to inspect the files and diffs. Review the agent’s explanation and test results, and ask for corrections before you merge.
Assistant publishes committed changes from Grafana sandbox tasks. Uncommitted changes aren’t published, and sandbox commands can’t push changes or open PRs directly.
The repository’s Managed Sandboxes setting in GitHub settings controls publishing:
- Ask before publishing: Assistant pushes nothing to GitHub until you approve. Click Create PR to push the branch and open a ready-for-review PR, or click Approve changes to push a follow-up to an existing PR. When the agent marks its work as not ready, the button reads Create draft PR and opens a draft PR. When the changes come from an investigation, Assistant also posts in the investigation’s Slack thread or incident that a fix is ready for review, with a Review changes link.
- Auto-publish draft PRs: Assistant can push branches and open draft PRs without asking. This option is available only for verified private repositories.
- Auto-publish ready PRs: Assistant can push branches and open ready-for-review PRs without asking, so code owners get review requests. The agent opens a draft instead when checks fail or didn’t run, or the work isn’t complete. This option is available only for verified private repositories. If you switch a repository to Auto-publish draft PRs, changes still waiting to publish open as drafts.
A PR that’s already open keeps its draft or ready state when Assistant pushes follow-up changes, with one exception: under Auto-publish ready PRs, a follow-up with new commits that the agent considers ready marks its draft PR ready for review. Assistant never turns a ready PR back into a draft.
Send follow-up instructions to update an existing PR. Follow its link to review and merge on GitHub. Approval to start an agent is separate from the repository’s publishing policy.
Customize your sandbox
The Default environment provides the standard image, public internet access, and global secrets. Customize a repository’s environment when it needs restricted network access, credentials, or additional tools. Each custom environment belongs to one repository. If you change network access or add a repository secret for a repository on the Default environment, Assistant creates a custom environment for it.
Grafana sandboxes run on AWS in the EU or US, based on your Grafana Cloud stack’s regional placement. They don’t necessarily use your stack’s cloud provider or exact region. Bring Your Own Cloud (BYOC) deployments aren’t supported in this public preview.
Configure sandbox environments
Create a custom environment for one repository, or edit its existing environment. You can also open it from Connectors > GitHub by clicking Default environment or Custom environment under the repository’s Managed Sandboxes setting.
- Open AI > Settings > Managed Sandboxes, select Grafana Cloud, and open the Environments tab.
- Click New environment and choose the repository. If the repository already has a custom environment, that environment opens instead.
- Under Network access, select Allow public internet, or select Allow only listed destinations. Enter each domain, for example,
example.comor*.example.com, and click Add. - Under Repository secrets, click Create secret to add any secrets only this repository needs. Refer to Add sandbox secrets for the available types and scopes.
- Click Create environment.
Click Edit to change an environment and Done to save network changes. Network access covers HTTP and HTTPS on ports 80 and 443; it doesn’t affect repository cloning. An empty destination list blocks internet access for sandbox commands.
For custom tools and dependencies, refer to Customize sandbox tools with a Dockerfile. To return a repository to the Default environment, remove its custom image first, if any, then click Delete environment. This also deletes its repository secrets.
Add sandbox secrets
Use secrets to let Grafana sandbox tasks authenticate with your services. Add a global secret under Managed Sandboxes > Grafana Cloud > Secrets, or open a repository’s environment to add a secret only that repository can use. If secrets aren’t available, ask your Grafana Cloud administrator to check access and availability.
- Click Create secret.
- Under Available to, choose Only me for runs made on your behalf, or Organization-wide for authorized runs across your organization, including automated investigations.
- Choose HTTPS credential to use a secret in requests without exposing its value to the agent. Choose Agent environment only when sandbox commands need to read the value as an environment variable. That value can appear in command output or the conversation.
- Enter Environment variable using uppercase letters, numbers, and underscores, for example,
REGISTRY_TOKEN. - For an HTTPS credential, enter HTTPS origin, for example,
https://registry.example.com, without a path. Optionally set Header to restrict the credential to one request header, for example,Authorization. - Enter the secret value and click Create secret.
Saved values aren’t displayed again. To replace a value, edit the secret and click Save changes. If saving fails, enter the value again before retrying. A secret doesn’t grant network access: allow its destination in the repository’s environment when you restrict internet access.
If secrets use the same environment variable name, your personal secret takes priority over an organization-wide secret. Within the same ownership scope, a repository secret takes priority over a global secret. If two secrets match at the same level, Assistant reports a conflict instead of choosing one.
Use Managed Sandboxes from other entry points
After you test a task in Assistant, start tasks from GitHub, Slack, or an automation. The repository’s access requirements and publishing policy still apply.
Ask questions from GitHub
When @grafana mentions is turned on for the repository, start an issue or pull request comment with @grafana to ask a question or request a code change:
@grafana explain how this pull request changes request timeout handling.Assistant replies on GitHub, where anyone who can see the issue or PR can read it. While it works, its comment links to the conversation in Grafana so you can follow its progress, and the reply replaces that comment when it finishes. To follow work that finishes later, for example, a merge, a CI run, or a rollout, ask Assistant to watch it. It posts status comments on the pull request for up to 24 hours.
Before you use mentions, link your GitHub account to your Grafana user. You need Assistant chat access and membership in the repository’s GitHub organization, or ownership of a personal-account installation. Coding tasks also need coding permissions and repository access.
Mentions work only on private and internal repositories.
Start coding tasks from Slack
After you connect Slack and link your Grafana account, ask @grafana to inspect a repository or implement a fix. Include the repository name and relevant error or investigation context. If Assistant asks you to link GitHub, complete setup and retry the request.
Assistant posts progress and PR links in the Slack thread. Follow the conversation link to review Changes in Grafana.
Run coding tasks with automations
Use an automation to run a coding prompt on a schedule, for example, to inspect infrastructure-as-code alert definitions and propose updates. Before you start, configure repository access and the repository’s PR policy.
Select the repository in Repository (optional) and describe the task in the instructions. Each run uses the active Managed Sandboxes provider and the repository’s permissions. Test the prompt with a manual run before you add a schedule under When to run.
Under Access and billing, choose which identity runs the automation:
- Personal access: manual runs use the invoker’s identity, and scheduled runs use the creator’s. Coding requires that user’s GitHub link and current repository permissions.
- Organization access: runs use the Assistant service account and the configured GitHub App policy. Choosing this option requires the Grafana organization Admin role.
Making an automation visible to Everybody doesn’t change which identity runs it.
The repository’s Managed Sandboxes setting also applies to automation runs. To create PRs without anyone clicking Create PR, choose Auto-publish draft PRs or Auto-publish ready PRs for a verified private repository. Review run results in the automation’s conversation. To get results in Slack or another destination, configure automation notifications.
Enable change reviews
Change review checks whether a pull request, once deployed, would hurt production. It reads the changed code and your stack’s live telemetry, and checks for five kinds of risk: deploy hazards, production impact, observability breakage, sensitive telemetry, and instrumentation.
When change review is available for your stack, open AI > Settings > Connectors > GitHub and turn on Change review for the repository. The setting saves immediately.
Assistant reviews open, ready-for-review pull requests that target the repository’s default branch.
Reviews run unattended with your stack’s service identity. They use Assistant’s Grafana tools, your stack’s shared rules and skills, and MCP servers shared with the whole stack. Reviews only read: they don’t change dashboards, alerts, or other resources, and tools that need an approval don’t run.
Customize change review checks
Change review runs each risk as a check. You can turn a built-in check off, choose whether it holds the merge, add instructions to it, or add checks of your own, for example, a check for database migrations that lock large tables. Checks apply to every repository with change review turned on, unless you limit them.
To change checks, you need permission to administer GitHub settings. Open Assistant > Settings > Connectors > GitHub and open the Review checks tab:
- Click Edit to change a check. Under Runs on, choose All repositories, Selected repositories, or Off. With Selected repositories, pick repositories from the list. Choose Blocking or Advisory: blocking checks fail the Grafana Assistant / Change Review check on GitHub when they confirm an issue. You can also add instructions to a built-in check or limit a check to file paths. A path such as
api/**/*.goruns the check only on pull requests that change a matching file, and**matches any number of directories. - Click Add check to describe a new check. Give it a name and tell the reviewer what to look for. Findings from the check show its name.
- To turn checks on or off for one repository, click Checks next to the repository’s Change review switch on the Repositories tab. These changes save immediately and show in each check’s Runs on setting. A check that runs on All repositories keeps running on repositories you turn change review on for later.
Reviews already running keep the checks they started with. A change to checks applies from the next review of each pull request, which reviews the whole change again.
Find out how your checks perform
Navigate to AI > Usage and open the Change review view to see what change review found over the last 7, 30, or 90 days, across every repository or for one you choose. The Review checks tab links to it. Use it to decide whether a check is worth its place, needs clearer instructions, or should be advisory. Activity appears once change review has published a review in the period. The view requires grafana-assistant-app.usage:read and permission to read GitHub settings.
The summary counts each issue once, across every review of its pull request:
- Reviews counts published reviews and the pull requests they covered.
- Issues found counts confirmed issues.
- Fixed is the share of issues a later review found resolved, out of the issues that were reviewed again. An issue a later review still raises counts as not fixed. An issue only the latest review raised isn’t counted until another review checks it.
- Merge holds counts the reviews that failed the Grafana Assistant / Change Review check.
The table below the summary breaks these numbers down by check, with Not reviewed again for issues no later review has checked yet, Unconfirmed for risks the review couldn’t confirm, and Ruled out for risks it disproved. Checks that found nothing are listed under the table.
To see the pull requests behind a check’s numbers, click its name in the table, or click Pull requests next to a check under Needs attention. Each pull request links to GitHub, and, if you can view change review runs, to its latest review run.
Needs attention lists checks whose numbers suggest a change. Click Edit check to open the check on the Review checks tab of the GitHub settings page:
- A check is noisy when the review ruled out at least half of five or more risks it raised. Add instructions or limit it to paths to focus it.
- A check that holds merges is often left unfixed when authors fixed fewer than a quarter of five or more issues it confirmed that were reviewed again. Consider making it advisory, or refine its instructions.
Only checks that are on are judged, using their current settings for the repository you chose, or for any repository when you look at all of them.
A line below the table shows how many reviews couldn’t check everything and why, for example, because Grafana checks failed or the reviewer couldn’t check everything it needed to.
Reviews are kept only as long as their review conversations, so activity can’t cover a longer period than your stack’s chat retention.
Read change review results
Assistant publishes the Grafana Assistant / Change Review check and inline comments for confirmed issues on GitHub. The check reports one of these results:
A failed check blocks the merge only if your branch protection requires it.
Assistant also posts one summary comment on each reviewed pull request. Later reviews update the same comment, even when the result becomes clean.
To keep pull requests with nothing to flag quieter, click Checks next to the repository’s Change review switch and turn off Comment on every pull request. Assistant then posts the summary comment only when the review holds the merge, confirms an issue, finds an unconfirmed risk that could hold the merge, or is incomplete. Otherwise, the pull request gets only the check, and you can’t start Monitor rollout from it.
To work on a confirmed issue, click its Fix in Grafana link to start a Workspace conversation. Unconfirmed risks don’t have this link. For requirements and the review workflow, refer to Fix a change review finding.
Use private repositories for change review and mentions
Change review and @grafana mentions are available only for private and internal repositories. You can’t enable them for public repositories, where anyone can see the comments.
Assistant checks repository visibility before each review and mention session, and again before publishing a review. If a repository becomes public, both features stop working there, including on stacks that previously allowed public repositories.
Monitor a reviewed pull request’s rollout
When Allow @grafana mentions is also enabled for the repository, the change review summary comment includes Monitor rollout. Click it on GitHub, then click Start monitoring in Grafana. Assistant creates an automation in your name and returns you to the pull request, where it posts a status comment that waits for the merge. After the pull request merges, each run checks in Grafana that the new version is live, how far the rollout has progressed, and how error rate and latency compare with before, then updates that comment.
Before you start, choose how long to keep checking after the merge: 1, 2, or 6 hours, with 2 hours by default. You can also say where to look, for example, a dashboard or a service label, and Assistant uses it as a starting point.
Nothing runs while the pull request is open. The checks run as you, with your Grafana permissions, and the automation appears in your automations. Checks stop at the end of the window you choose, and no later than 24 hours after you start, so start close to when you plan to merge.
You need a linked GitHub account that belongs to the repository’s GitHub organization, the same requirement as an @grafana mention. If your Grafana administrator hasn’t set up GitHub account linking, the button doesn’t appear. Opening the link alone starts nothing. If you’re already monitoring the pull request, the page shows that monitor and a link to manage it in your automations. Starting again after your monitor ended, or after you turned it off or deleted it, creates a new one.
Next steps
For more ways to work with Managed Sandboxes, refer to these guides:


