---
title: Environments and Sandboxes (public)
description: A Harness Runtime environment is a reusable configuration object defining what an agent needs to do work, and a sandbox is the isolated microVM a …
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/environments/
last_updated: "2026-09-28"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# Environments and Sandboxes (public)

DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases.

## Environment

An *environment* is a reusable configuration object that defines what an agent needs to do work. It specifies the agent or framework to run, the sandbox’s compute resources, and the skills, tools, credentials, and permissions available to the agent.

Starting a [session](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/sessions/index.html.md) from an environment provisions an isolated sandbox using that configuration. The environment defines the setup; the sandbox is the machine where the agent and its code run. You can use the same environment to start multiple sessions, each with its own sandbox. You define an environment in an [environment spec](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md) or build the equivalent in the Control Panel.

An environment is immutable once created. Changing its [adapter](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/agent-adapters/index.html.md), credentials, or permissions requires creating a new environment, keeping each session traceable to the configuration it started with.

### What an Environment Declares

| Declaration | What it sets |
|---|---|
| `agent` | The [adapter](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/agent-adapters/index.html.md), which selects the coding agent or framework and the sandbox image that boots. |
| `size` | The vCPU and memory allocation of the sandbox. |
| `skills` | Inline instructions the agent loads, in the Agent Skills (`SKILL.md`) shape. |
| `secrets` and `env` | Credentials and plain configuration. See [Secrets and Configuration](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/secrets/index.html.md). |
| `permissions` | What the agent may do, must ask about, or may never do. See [Permission Policies](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/permissions/index.html.md). |
| `tools` | MCP servers and [Action Gateway](https://docs.digitalocean.com/products/managed-agents/action-gateway/index.html.md) tools the agent can call. |
| `egress` | An allowlist of hosts the sandbox may reach. Unrestricted when omitted. See [Network Egress](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/egress/index.html.md). |
| `repos` | Repositories the agent is meant to work on. A hint, not a checkout; nothing is cloned for the agent. |

### Environment Configs

Saving an environment so you can start sessions from it repeatedly, without resupplying credentials, gives you an Environment Config. See [Use Environment Configs](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-agent-configs/index.html.md).

## The Sandbox

A *sandbox* is the isolated microVM provisioned for a session. It provides the CPU, memory, filesystem, and toolchain the agent uses to execute code and work with files. Its size and image are determined by the environment. Isolation is enforced by the hypervisor rather than by container namespaces, so a process in one sandbox cannot observe or reach another session, another customer, or the host. Harness Runtime manages its lifecycle, including provisioning, pausing, resuming, and removal when you delete the session.

The environment also defines the credentials available to the agent and, when it sets an egress allowlist, the network destinations the sandbox is confined to. Listing a repository under `repos` tells the agent which repository it is meant to work on; it does not clone the repository into the sandbox. To harden credentials, egress, and cleanup across adapters, see [Secure Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/secure-sessions/index.html.md).

### Sandbox Sizes

A sandbox has a fixed vCPU and memory allocation, chosen through the `size` field. Size cannot change on a running session, and a session restored from a checkpoint keeps the size of the sandbox the checkpoint came from. For the available values, see the [environment spec reference](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md).

### Sandbox Images

The sandbox boots from an image that already contains the agent, its dependencies, and the in-sandbox runtime that supervises it. The adapter you choose selects the image, and setting `template` pins a different one.

Teams that need extra tooling in every sandbox can build a custom image on top of a DigitalOcean base image and reference it from the environment. See [Use a Custom Template](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-custom-template/index.html.md).

### Workspace (Beta)

A *Workspace* is a separate drive mounted inside the sandbox at `/workspace`. Cloned repositories, uploaded files, agent edits, and build artifacts live there, and it is the default root for filesystem permission rules.

Its lifecycle is independent of the session. Files written to the Workspace drive persist after you remove the session. Pausing and resuming leave Workspace content in place with the rest of the sandbox state.

Use Workspace for repositories, datasets, and generated artifacts that need to outlive the execution that produced them. For example, an agent can analyze uploaded documents and save a report to the Workspace drive, so you can remove the session while retaining the source material and results.