Skip to main content

​
Overview

Sandbox profiles define the execution environment an agent starts with. Use a sandbox profile to control:
  • the agent runtime, such as Codex or OpenCode
  • the sandbox runtime, such as Docker or E2B
  • installed tools and runtimes
  • setup scripts
  • allowed integrations and connection behavior
  • repository access through a Git connection
  • environment configuration required for agent work
Profiles make agent environments repeatable. Instead of configuring every session by hand, teams publish profile versions and start sessions from those published versions.

​
Draft And Published Versions

Sandbox profile changes are made as drafts. Publishing a profile version makes that configuration available for new sessions. Published versions are immutable from the point of view of future sessions. To change the environment, edit the draft and publish a new version.

​
Publish A Working Profile

A usable profile usually needs more than a name and base image. Before publishing, configure the pieces the agent will need at runtime:
  1. Create or edit a sandbox profile draft.
  2. Choose the agent runtime.
  3. Choose the sandbox runtime and credentials.
  4. Select the model provider, Git connection, and connector integrations the profile should expose to sessions.
  5. Add repository or workspace configuration when the agent should work in source code.
  6. Write and test the setup script.
  7. Publish the profile version.
  8. Wait for the snapshot to become ready.
  9. Start a session from the published profile.
Sandbox profile draft editor showing runtime, Git connection, model provider, connector integrations, and tools
If the snapshot fails or stays unavailable, sessions cannot start from that published profile version until the snapshot is fixed or refreshed.

​
Runtime And Connections

The Runtime section controls what kind of agent starts and where it runs:
  • Agent chooses the agent runtime. Codex profiles use OpenAI-compatible model provider connections. OpenCode profiles can use OpenCode-compatible provider connections such as Anthropic and OpenCode Go.
  • Sandbox Runtime chooses where the sandbox runs. Docker is used for local or self-hosted Docker deployments. E2B can be selected when the deployment and integration target expose it.
  • Credentials controls whether the sandbox runtime uses Mistle-managed credentials or a workspace API key connection, when that provider supports both.
  • Git Connection controls which Git provider connection supplies repositories and repository tools.
Model provider connections, Git connection, and connector integrations are saved on the draft profile version. Publishing the profile version makes those choices available to new sessions and triggers.

​
Setup Scripts

Setup scripts are custom preparation steps that run during snapshot creation. They make the profile’s starting environment explicit and repeatable, instead of leaving future sessions to depend on manual setup or agent-discovered setup work. 
Base image
  ↓
Mistle prepares the profile-defined environment
  - agent runtime and configuration
  - repositories
  - integration-related MCP tools and configuration
  ↓
Setup script runs
  ↓
Snapshot captured
Mistle first prepares the profile-defined environment from the sandbox profile. The setup script then runs on top of that environment before the snapshot is captured. Keep setup scripts deterministic and explicit. A session should not depend on manual setup that is not captured in the profile.

​
Use Setup Assistant

Setup Assistant opens an agent workspace beside the setup script editor so you can ask an agent to build or fix the draft setup script for the current profile. The assistant sandbox automatically has Mistle MCP enabled for the selected draft profile version. That lets the assistant read the profile context, update the draft setup script, and start setup-script test runs from inside its workspace. To use Setup Assistant:
  1. Open a sandbox profile draft.
  2. Make sure the profile includes a model provider connection for the selected agent runtime.
  3. Select Setup Assistant from the setup script controls.
  4. Tell the assistant what the setup script needs to accomplish.
  5. Let the assistant write the script, run setup-script tests, and update the draft setup script.
  6. Review the updated setup script and test output before publishing the profile version.
Sandbox profile setup script editor with the Setup Assistant panel open
Setup Assistant is only available while editing a draft profile version, and it requires a model provider connection for the selected agent runtime. The assistant sandbox starts from the base image so the saved script does not depend on state created only inside the assistant session.

​
Experiment With Setup Scripts

Setup script changes are made on draft profile versions. Published versions are read-only. To experiment with a setup script:
  1. Open the sandbox profile.
  2. Edit the draft version.
  3. Update the Setup script field.
  4. Use Setup script behavior to confirm where repositories are cloned and which tools are available.
  5. Select Test setup script to run the script in a temporary sandbox.
  6. Inspect the test output, adjust the script, and test again.
  7. Publish the profile version when the script is reliable.
Sandbox profile setup script editor with setup script behavior, Test control, and setup test output
Setup script testing is only available while editing a draft, and only after the script has content.

​
Snapshots

When a profile version is published, Mistle can prepare a snapshot for that version. The snapshot captures the prepared environment so new sessions can start from the profile-specific image instead of rebuilding from the shared base image every time. Read Snapshots for the snapshot lifecycle.

​
Triggers On A Profile

Open the Triggers tab on a sandbox profile to see triggers that use that profile. From there you can create a new trigger preselected for the profile, or select an existing event or scheduled trigger to edit it without leaving the profile.
Sandbox profile Triggers tab showing profile-scoped trigger list and selected trigger editor

​
Next Steps