Agent Sandbox

The SubImage assistant can do more than answer questions: it can run real commands on your behalf. When a task needs to clone a repository, run a tool, build a report, or open a fix as a pull request, the assistant works inside an isolated Linux sandbox rather than in the SubImage backend itself. This page explains what the sandbox can do, how it is secured, and how the assistant opens a pull request.

Capabilities

The sandbox is a generic command environment, prepared automatically the first time the assistant needs it in a conversation. There is no setup step for you to perform. Inside it the assistant can:

• Run shell commands: git, the GitHub CLI, language toolchains (Python, Node, Go), build and test tools, linters, and structured-data utilities such as jq and yq.
• Run supported cloud CLIs for read operations across AWS, GCP, Azure, Scaleway, and Databricks.
• Read and write files in its workspace, for example to edit a repository it has cloned.
• Build a document for you (Word, Excel, PowerPoint, PDF, plain text, CSV, JSON) and hand it back as a download link.
• Open a pull request for a change it has prepared and update pull requests opened by the SubImage Agent.

The workspace for a conversation persists across turns, so the assistant can pick up where it left off within the same thread.

Security model

The sandbox is built so the assistant can act usefully without being able to reach beyond what your team has authorized.

• Isolation per session. Each chat thread runs in its own sandbox, scoped to the signed-in user. One user cannot reach another user's workspace, even within the same organization.
• Direct-command policy. The command interface admits a reviewed set of tools and rejects direct use of utilities such as curl and wget. This is a safety filter, not the isolation boundary: language runtimes and build tools can execute repository code.
• Read-oriented cloud access. AWS, GCP, and Azure use read-only provider credentials plus command checks. Scaleway and Databricks use fail-closed read-operation allowlists when their configured credentials may carry broader permissions.
• Per-command, scoped credentials. Credentials are never left lying around in the environment. A credential (a GitHub token, or a read-only cloud credential) is injected into a single command, only when that command needs it, and a cloud credential is accepted only by its own CLI.
• Restricted network posture. The sandbox permits HTTPS and DNS egress. It does not currently enforce an FQDN allowlist, so session isolation, privilege separation, and per-command credentials remain the primary security boundaries.

Pull request creation

When the assistant has prepared a fix, it can open a pull request directly. The flow is:

1. The assistant clones the repository, creates a branch, edits the files, and commits, all inside the sandbox.
2. It proposes opening a pull request. This always pauses for your approval. You see the target repository, the branch, the base branch, and the change before anything is pushed.
3. Once you approve, SubImage pushes the branch and opens the pull request, and returns you the link. If the branch has no new commits over the base, the request is rejected rather than opening an empty PR.

When the change fixes a known SubImage item (an issue, vulnerability, finding, or attack path the conversation is about), the pull request is linked back to that item so the remediation is tracked.

The assistant can push follow-up commits or update the title, description, and draft status of a pull request opened by the SubImage Agent. It cannot use this flow to modify a pull request opened by a person or another application.

A separate GitHub App for writes

Reading your repositories and writing to them use two different GitHub Apps, on purpose:

• SubImage Sync (github.com/apps/subimage-sync) is the read-only App that inventories your repositories. It is what the assistant uses to clone code. It cannot push or open pull requests.
• SubImage Agent (github.com/apps/subimage-agent) is a separate App with write permissions (repository contents and pull requests), used only to push a branch and open a remediation pull request.

Keeping the write scope in its own App means the read-only inventory connection never carries write access. The assistant can only push to an organization where your team has installed the SubImage Agent App itself, and the write token is minted server-side for a single push, never handed to a command the assistant controls. Until the Agent App is installed, the assistant can still clone and prepare changes, but opening a pull request will be unavailable.

To enable pull request creation, install the SubImage Agent App on the organizations you want from the Integrations settings page.