For AI agents: The documentation index is at 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).

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.

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.
• Harness Runtime prepayment with a positive balance.

Write the Environment Spec

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

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.

Create the Session

Create the session from the spec:

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

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

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:

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

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

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:

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:

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

Download a result after a command produces it:

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.

Forward a Port

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

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:

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.

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:

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:

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.

Checkpoint, fork, and rollback are not available for a sandbox without a harness. See Manage Sessions for the full lifecycle commands.