---
title: How to Run a Sandbox on DigitalOcean Harness Runtime (public)
description: Start a Harness Runtime sandbox with no harness in it, then run commands, transfer files, and forward ports with doctl.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/run-sandbox/
last_updated: "2026-10-27"
---

> **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).

# How to Run a Sandbox on DigitalOcean Harness Runtime (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.

You can run a DigitalOcean Harness Runtime sandbox with no harness in it. You get the same hardware-isolated microVM that a coding agent would run in, and you drive it yourself with `doctl harness-runtime exec`, `upload`, `download`, and `port-forward`. Use a sandbox this way to execute code your own application generates, run a build or test suite in isolation, or host a service that you reach through a port forward.

The sandbox runs commands as `root` and starts in the `/workspace` directory. The base image is Ubuntu 24.04 with Git, Python 3 (with `pip` and `venv`), Node.js 20, the GitHub CLI (`gh`), `curl`, and a C build toolchain (`build-essential`). To start from an image with your own tooling preinstalled, see [Use a Custom Template](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-custom-template/index.html.md).

You can create a sandbox without a harness using `doctl` or the API. The Control Panel does not offer this option.

## Prerequisites

- [`doctl` installed and authenticated](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/quickstart/index.html.md#install-doctl).
- [Harness Runtime prepayment](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/pay-for-harness-runtime/index.html.md) with a positive balance.

## Write the Environment Spec

Create a file named `sandbox.yaml` and set `harness` to `none`:

```yaml
name: my-sandbox
harness: none
size: mars-2vcpu-4gb
egress:
  - pypi.org
  - files.pythonhosted.org
  - registry.npmjs.org
```

A sandbox without a harness accepts the following spec fields:

- `harness` (required): Must be `none`.
- `name` (optional): Session name. Generated when not provided.
- `size` (optional): Sandbox size slug. Defaults to `mars-2vcpu-4gb`.
- `env` (optional): Non-secret environment variables for commands you run.
- `secrets` (optional): Credentials, exposed as environment variables in the sandbox.
- `egress` (optional): Outbound allowlist. Unrestricted when omitted.
- `skills` (optional): Accepted, but no agent is present to load them.

The agent-oriented fields do not apply. `permissions` and `tools` have nothing to govern or attach to, and `idle_timeout` and `keep_warm` are not honored, so pause the session yourself when you are done with it. For field details, see the [Environment Spec Reference](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md).

## Create the Session

Create the session from the spec:

```shell
doctl harness-runtime create --spec ./sandbox.yaml
```

To create the sandbox without a spec file, omit `--harness` and pass the `sandbox` template directly:

```shell
doctl harness-runtime create --name my-sandbox --template sandbox
```

Either command waits until the sandbox is ready and prints a summary. There is nothing to attach to, so `doctl harness-runtime launch` is not used with a sandbox that has no harness.

## Run Commands

Run a command in the sandbox with `exec`. Each call is independent, so a directory change in one call does not carry to the next:

```shell
doctl harness-runtime exec my-sandbox -- python3 --version
```

The command’s output and exit code return to your terminal:

```text
Output
Python 3.12.3
```

Commands run in `/workspace` by default. To run a command in another directory, pass `--workdir`, and to run several commands in one shell, wrap them with `sh -c`. The following commands clone a repository into the workspace, then install its dependencies and run its tests:

```shell
doctl harness-runtime exec my-sandbox -- git clone https://github.com/<your-org>/<your-repo>.git
doctl harness-runtime exec my-sandbox --workdir /workspace/<your-repo> -- sh -c "npm install && npm test"
```

## Transfer Files

Upload an input file into the sandbox workspace:

```shell
doctl harness-runtime upload my-sandbox \
  --local-file ./input.csv \
  --workspace-path input.csv
```

Download a result after a command produces it:

```shell
doctl harness-runtime download my-sandbox \
  --workspace-path report.json \
  --save-to ./report.json
```

For directory transfers and size limits, see [Upload and Download Session Files](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/transfer-files/index.html.md).

## Forward a Port

To run a server in the sandbox, start it in the background with its output redirected to a file:

```shell
doctl harness-runtime exec my-sandbox -- sh -c "nohup python3 -m http.server 8080 > /tmp/server.log 2>&1 &"
```

The redirect lets `exec` return right away while the server keeps running. Without it, `exec` waits on the server’s output instead of returning.

Open a tunnel to the server:

```shell
doctl harness-runtime port-forward my-sandbox 8080
```

Then open `http://127.0.0.1:8080`. Nothing in the sandbox is published to the internet, and the tunnel closes when you stop the command. See [Forward Sandbox Ports](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/forward-ports/index.html.md).

## Pause, Resume, and Remove the Sandbox

The sandbox bills for its compute until you pause or remove it, and it does not pause on idle. Pause it when you are not using it, resume it to continue, and remove it when the work is finished:

```shell
doctl harness-runtime pause my-sandbox
doctl harness-runtime resume my-sandbox
doctl harness-runtime remove my-sandbox
```

Creating the sandbox also saved its spec as an Environment Config, and removing the sandbox does not delete that config. Each new sandbox you create saves another one. The `create` output shows the config ID, labeled as an Agent Config, the earlier name for an Environment Config. You can leave the config in place. To delete it after you remove the sandbox, run:

```shell
doctl harness-runtime config delete <config-id>
```

To find the ID later, run `doctl harness-runtime config list`. For details, see [Delete an Environment Config](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-agent-configs/index.html.md#delete-an-environment-config).

Checkpoint, fork, and rollback are not available for a sandbox without a harness. See [Manage Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/manage-sessions/index.html.md) for the full lifecycle commands.