---
title: How to Use Environment Configs (public)
description: Save a Harness Runtime spec as a reusable Environment Config, then start sessions from it without resubmitting the YAML.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-agent-configs/
last_updated: "2026-10-13"
---

> **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 Use Environment Configs (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.

Starting a [Harness Runtime](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/index.html.md) session with `doctl harness-runtime create --spec` uploads the YAML spec each time and saves it as a new Environment Config with the session’s name. That config remains after the session ends. When you run the same setup repeatedly, save it once as a named Environment Config and start as many sessions from it as you need.

An Environment Config is immutable. It always produces the same environment, so a config ID always refers to one specific configuration.

## Create an Environment Config

Create a config from a spec file and give it a name. To write the spec first, see [Create an Environment Using a Coding Adapter](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/create-managed-agent/index.html.md).

```shell
doctl harness-runtime config create --spec codex-spec.yaml --name my-codex-setup
```

Credentials in a config are handled the same way as credentials in a session spec. Values you declare under `secrets` go to DigitalOcean Secrets Manager when the config is created. Values under `env` stay debug-readable inside the sandbox, so keep credentials out of `env`. For the full field list, see the [Environment Spec Reference](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md).

Because a config is immutable, changing a setup requires creating a new config from the updated spec.

## Start a Session from an Environment Config

List the saved configurations to find the name or ID of the one you want:

```shell
doctl harness-runtime config list
```

Start a session from that config:

```shell
doctl harness-runtime config start-session <config-name-or-id> --name <your-session-name>
```

Alternatively, you can use the `--from-config` flag:

```shell
doctl harness-runtime create --from-config <config-name-or-id> --name <your-session-name>
```

The session runs the setup defined in the config. Attach to it, pause it, and remove it with the usual commands, described in [Manage Harness Runtime Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/manage-sessions/index.html.md).

## Trace a Session Back to Its Config

Every session records the config it started from. To see the config for a single session, show the session:

```shell
doctl harness-runtime show <your-session-name>
```

To list every session a config has produced, pass the config ID:

```shell
doctl harness-runtime config list-sessions <config-id>
```

## Delete an Environment Config

Delete a config you no longer need, or one that blocks [revoking a GitHub connection](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/connect-github/index.html.md#revoke-a-connection). Find the config ID with `doctl harness-runtime config list`, then delete it:

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

You cannot delete a config while it has active sessions. List them with `doctl harness-runtime config list-sessions <config-id>`, [remove each session](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/manage-sessions/index.html.md), and then delete the config.

After you delete a config, no one on your team can start sessions from it.