> ## Documentation Index
> Fetch the complete documentation index at: https://laminar.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Laminar Agent Sandbox: Work in Your GitHub Repositories

[Laminar Agent](https://laminar.sh/docs/platform/laminar-agent.md) can work in your project's GitHub repositories inside a **sandbox**: a private Linux VM with your repositories cloned into it. In the sandbox the agent reads code, edits files, runs commands, and opens pull requests. Use it to trace a failure back to the code that caused it, add or fix Laminar instrumentation and check that the traces arrive, or write [agent evaluations](https://laminar.sh/docs/agent-evaluations/introduction.md) and run them.

A sandbox keeps your work between conversations. When it has been idle for 30 minutes it stops, and its files are saved. The next time the agent needs it, the sandbox comes back as it was, for up to 30 days.

## Set up the agent sandbox

The agent sandbox is a per-project setting that decides which repositories the agent clones and which LLM keys it gets. Only workspace owners and admins can change it.

![Agent sandbox settings page with a Repositories list of four GitHub repositories, two turned on with branch pickers set to staging and main, and an LLM profiles list with two of three profiles turned on](https://mintcdn.com/laminarai/NJOqyfLAJw930MrG/images/platform/agent-sandbox-settings.png?fit=max\&auto=format\&n=NJOqyfLAJw930MrG\&q=85\&s=6ec492754971d912c7857ad6fd79f40b)

Settings > Agent sandbox: two repositories cloned into the sandbox, each at its own branch, and the LLM profiles whose keys the sandbox gets

**1. Connect GitHub**

Go to **Settings > Integrations**, under **Workspace settings**, and connect GitHub. Install the Laminar GitHub App on the organization or account that owns your repositories, and give it access to the repositories you want the agent to work in. A GitHub account can be connected to one Laminar workspace.

![Workspace Integrations page with a connected GitHub card for the acme-ai account and an Agent sandbox settings button](https://mintcdn.com/laminarai/NJOqyfLAJw930MrG/images/platform/agent-sandbox-github.png?fit=max\&auto=format\&n=NJOqyfLAJw930MrG\&q=85\&s=13669a394c9317240401d05fad7e4be6)

Once GitHub is connected, the card shows the GitHub account and links to the Agent sandbox settings

**2. Pick the repositories**

In the project, go to **Settings > Agent sandbox** and turn on each repository you want cloned into the sandbox. The list shows every repository the GitHub App can access. To add a repository that isn't listed, click **Manage access on GitHub** and grant the app access to it.

**3. Pick a branch for each repository**

Each selected repository has a branch picker. Leave it on the repository's default branch, or search for and pick another branch. A new sandbox clones each repository at that branch, and pull requests from the agent target it.

![Branch picker open on the acme-ai/support-bot repository, with a branch search box, main marked as default, and staging selected](https://mintcdn.com/laminarai/NJOqyfLAJw930MrG/images/platform/agent-sandbox-branch-picker.png?fit=max\&auto=format\&n=NJOqyfLAJw930MrG\&q=85\&s=4522b29f21b4faa6c66103cc3c34500c)

The branch picker lists the repository's branches, with the default branch first

**4. Pick the LLM profiles**

Under **LLM profiles**, select the [LLM profiles](https://laminar.sh/docs/platform/llm-profiles.md) whose API keys the sandbox should get. Do this when the code in your repositories calls an LLM and you want the agent to run it, for example to check that a change produces the trace you expect.

The branch setting applies when a sandbox is created. A sandbox that already exists keeps the branch it has, so start a new chat to work from a branch you changed.

## What is in a sandbox

Each sandbox is a Linux VM with git, Node.js, Python, and Docker. Every repository in the environment is cloned into `~/repos/<repository name>`, and the agent installs dependencies itself when it needs them.

Commands in the sandbox get these environment variables:

* **LLM keys** from the selected profiles, under each provider's usual names: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, the `AWS_*` variables for Bedrock, and the `AZURE_*` variables for Azure. Custom gateway profiles get variables prefixed with `CUSTOM_LLM_`.
* **`LMNR_PROJECT_API_KEY`**, a project API key that belongs to this sandbox only. The agent uses it to send traces from your code to the project and to run evaluations. A new key is created every time the sandbox starts. It is revoked after the sandbox stops, and expires after 24 hours at the latest. These keys don't appear on the project's API keys page.
* **`LMNR_BASE_URL`**, the Laminar API the key works with.

The sandbox has no GitHub credentials. The agent pushes through Laminar, which only pushes to `laminar/` branches and opens pull requests (see [Review the agent's pull requests](#review-the-agents-pull-requests)).

## Ask the agent to work in your code

Ask from the **Agent** panel in the Laminar app, or from your terminal with [`lmnr-cli ask`](https://laminar.sh/docs/platform/cli#ask-the-agent). Only workspace owners and admins can use the sandbox. The agent doesn't open a sandbox when you ask from [Slack](https://laminar.sh/docs/platform/integrations.md#laminar-agent) or the [MCP server](https://laminar.sh/docs/platform/mcp.md).

The agent opens the sandbox when a question needs your code, so you don't have to ask for it. Some things to ask:

* "Find the cause of the errors in the latest failed trace and fix it."
* "Add Laminar tracing to the support agent in `support-bot`, run it once, and check that the trace looks right."
* "Write evals for the cluster about invented hotel prices and run them."
* "Continue the eval work in the sandbox from my teammate's chat."

On a Signal's cluster, the **Create Evals** button starts a chat that asks the agent to write evals from that cluster and run them. The agent runs evals with [`lmnr-cli eval run --remote`](https://laminar.sh/docs/agent-evaluations/running-evals), so each run shows up in the project's evaluations, with a trace for every trial.

Laminar Agent also reads your code when it writes [cluster reports](https://laminar.sh/docs/signals/clusters.md), once the project has repositories in its agent sandbox settings. That sandbox is read-only for the agent: it gets no LLM keys or project API key, and it can't push or open pull requests.

## Review the agent's pull requests

When the work is done, the agent commits its changes and pushes them to a new `laminar/` branch in your repository, then opens a pull request against the branch the sandbox cloned. It replies with the pull request link. Later pushes from the same sandbox add commits to the same pull request.

Commits arrive signed by GitHub, so they show as **Verified**. The agent can't push changes to `.github/workflows/`.

The agent can also pull the latest commits of that branch into the sandbox, rebasing its own commits on top. If it had already pushed, its next push opens a new pull request from the updated branch.

## Sandboxes stop when idle and resume where they left off

A sandbox stops after 30 minutes with no commands running. A command that is still running counts as activity, so a long build or eval run keeps the sandbox up. A sandbox also stops after running for 24 hours.

When a sandbox stops, Laminar saves its whole filesystem:

* the repositories, including commits and uncommitted changes
* installed dependencies, build output, and Docker images

Running processes, such as dev servers, watchers, and Docker containers, are not saved. Docker itself starts again when the sandbox resumes.

The next time the agent needs the sandbox, in the same chat or from another one, it starts a new VM from the saved files and carries on. You don't need to do anything for this. A restored sandbox gets a new `LMNR_PROJECT_API_KEY`.

A saved sandbox is kept for 30 days after it was last used. After that, the chat's next request starts a fresh sandbox, cloned again from the environment's branches, and any work in the old sandbox that wasn't pushed is gone. Ask the agent to open a pull request for work you want to keep.

## Sandboxes are shared across the project

Sandboxes belong to the project, not to one chat. The agent can list the project's running and saved sandboxes, including the ones your teammates' chats created, and switch your chat to one of them. It only opens a teammate's sandbox when you ask it to, since the work in it is theirs. Sandboxes used for cluster reports are not listed.

A project can have up to 10 sandboxes running at the same time. Stopped sandboxes don't count toward this limit.

Deleting a chat doesn't delete its sandbox right away: the sandbox stops when it goes idle, and its saved files are deleted 30 days after it was last used.

## What's next

> [card] [Laminar Agent](https://laminar.sh/docs/platform/laminar-agent.md)
>
> Everything the agent can do, and where you can ask it.

> [card] [Agent evaluations](https://laminar.sh/docs/agent-evaluations/introduction.md)
>
> How the evals the agent writes and runs are structured.

> [card] [Clusters](https://laminar.sh/docs/signals/clusters.md)
>
> The groups of Signal events the agent writes reports and evals from.

> [card] [LLM profiles](https://laminar.sh/docs/platform/llm-profiles.md)
>
> Add the provider keys the agent sandbox hands to your code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.