---
title: How to Update the Settings of a DigitalOcean Harness Runtime Session (public)
description: Change the tools, environment variables, secrets, or model of an existing Harness Runtime session in place, without creating a new session or …
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/edit-session-configuration/
last_updated: "2026-11-20"
---

> **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 Update the Settings of a DigitalOcean Harness Runtime Session (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.

A session starts with the settings of the [environment](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/environments/index.html.md) it was created from. You can change some of those settings after the session starts, without creating a new environment or a new session. The session keeps its conversation history and the files in its workspace.

Use this to add or remove tools, change environment variables, switch the model, or rotate a credential such as a GitHub personal access token on work that is already in progress. An update applies to one session. Other sessions, and the environment the session was created from, are not changed.

**Note**:

  Updating session settings is in [public preview](https://docs.digitalocean.com/platform/product-lifecycle/index.html.md#public-preview) and is enabled per team. If your team is not enrolled, update requests return a `403` error. To request access, contact your DigitalOcean account team.

## Prerequisites

- A session that uses the Claude Code, OpenCode, Codex, Hermes, or LangGraph adapter. Sessions that use other adapters return a `409` error.
- A session that is idle, with no turn or approval in progress. A paused session can be updated, and it returns to the paused state when the update finishes. A session that was paused for a zero balance cannot be updated.
- A team that is enrolled in the public preview.
- `doctl` installed and authenticated. See [Quickstart](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/quickstart/index.html.md).

## What You Can Change

| Setting | Can you change it? | What happens |
|---|---|---|
| `tools` | Yes | The change applies while the session runs. A tools-only update usually takes a few seconds. |
| `env` | Yes | The agent restarts to apply the change. This can take about two minutes. |
| `secrets` | Yes, for key and value secrets | The agent restarts to apply the change. This can take about two minutes. |
| Model | Yes, through `env` | Set `HARNESS_INFERENCE_MODEL` in `env`. This works only for sessions that use DigitalOcean Serverless Inference. See [Change the Model](#change-the-model). |
| `permissions` | No | The request returns a `400` error. |
| Anything else, such as `harness`, `size`, `egress`, or `skills`, or a top-level `model` section | No | The request returns a `400` error. To change these, create a new environment and session. |

## How an Update Works

You describe a change with a partial manifest, a YAML file that holds only the sections you want to change. The sections you leave out are not touched. Inside a section you do include, the rules are different:

- `tools` is the full replacement list. Every tool or MCP server you leave out of the list is detached. `tools: []` detaches all of them.
- `env` is a full set. A key you leave out is removed.
- `secrets` is a full set. A key you leave out is removed. A string value sets or rotates the secret, and `{}` keeps its current value.

**Warning**:

  Because `tools`, `env`, and `secrets` replace their whole section, send every entry you want to keep, not only the one you are changing. Leaving an entry out removes it from the session.

An update is applied as a single change. If it fails, Harness Runtime reverts the session to its previous settings. Only one update runs on a session at a time, and an update is rejected while a turn or an approval is in progress.

An update that changes nothing returns an `UNCHANGED` outcome and records nothing.

## Add or Remove Tools

Write a manifest that holds the complete list of tools the session should have afterward, including any MCP servers you want to keep. The following example gives the session two Action Gateway tools:

```yaml
tools:
  - do.actions:
      tools: [exa_web_search, exa_web_fetch]
```

Save it as `tools.yaml`, then apply it to the session:

```shell
doctl harness-runtime update <your-session-name> --spec tools.yaml
```

You can also read the manifest from standard input:

```shell
doctl harness-runtime update <your-session-name> --file - < tools.yaml
```

For the fields a tool entry accepts, see [`tools`](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md#tools) in the environment spec reference. Attaching a tool does not grant permission to call it. Permissions stay as the environment set them.

To detach every tool from the session, send an empty list:

```yaml
tools: []
```

## Rotate a GitHub Personal Access Token

If you gave the session a GitHub personal access token as a secret, you can rotate it on the session. Revoke the old token on GitHub only after the update completes. See [Use a Personal Access Token](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/connect-github/index.html.md#use-a-personal-access-token) for how the token is declared.

Export the new token in your shell so `doctl` can expand the placeholder before upload:

```shell
export GITHUB_TOKEN=<your-new-github-token>
```

Write a manifest that lists every secret the session has. Give the secret you are rotating its new value, and use `{}` for the rest to keep their current values:

```yaml
secrets:
  OPENAI_API_KEY: {}
  GITHUB_TOKEN: ${GITHUB_TOKEN}
```

Apply it:

```shell
doctl harness-runtime update <your-session-name> --spec secrets.yaml
```

The agent restarts to pick up the new value, so the update can take about two minutes. Secret values are write-only. No command or API response returns a secret value after you submit it.

You can update key and value secrets only, which are secrets you set to a string. You cannot update a scoped secret, which binds a credential to one HTTPS destination with `url`, or an OAuth connection slot such as a GitHub connection. Send these back unchanged. A request that changes them, or that changes a key the platform manages for the adapter, returns a `422` error because the change needs a new session. To use a different GitHub OAuth connection, create a new session. See [Connect GitHub](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/connect-github/index.html.md).

## Change Environment Variables

Write a manifest that lists every environment variable the session should have. Use `env` for plain configuration only. Put credentials under `secrets`:

```yaml
env:
  FEATURE_FLAG: "on"
  LOG_LEVEL: debug
```

Apply it the same way:

```shell
doctl harness-runtime update <your-session-name> --spec env.yaml
```

The agent restarts to apply the change, so the update can take about two minutes. Platform-reserved variables, such as `SESSION_ID` and `TEAM_ID`, cannot be set and must be left unchanged. For the list, see [Secrets and Configuration](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/secrets/index.html.md#reserved-environment-variables). If the session uses DigitalOcean Serverless Inference, its `env` also includes `HARNESS_INFERENCE_MODEL`, `HARNESS_INFERENCE_API_KEY`, and `HARNESS_INFERENCE_BASE_URL`. Include all three in every `env` update, and send `HARNESS_INFERENCE_API_KEY` and `HARNESS_INFERENCE_BASE_URL` with their current values. Leaving any of them out, or changing the two platform-managed keys, returns a `422` error.

## Change the Model

To switch the model of a session that uses DigitalOcean Serverless Inference, set `HARNESS_INFERENCE_MODEL` in `env`. Because `env` is a full set, include every other variable you want to keep. Send `HARNESS_INFERENCE_API_KEY` and `HARNESS_INFERENCE_BASE_URL` with their current values, because the platform manages them and a request that drops or changes them returns a `422` error:

```yaml
env:
  HARNESS_INFERENCE_MODEL: <your-model-id>
  HARNESS_INFERENCE_API_KEY: <current-value>
  HARNESS_INFERENCE_BASE_URL: <current-value>
  FEATURE_FLAG: "on"
```

Apply it:

```shell
doctl harness-runtime update <your-session-name> --spec env.yaml
```

This is an `env` change, so the agent restarts and the update can take about two minutes. You cannot change the model of a session that uses a third-party model this way, and a top-level `model` section in the manifest returns a `400` error.

## Check the Result

By default, `doctl` waits until the update finishes, for up to 300 seconds. To change the wait, use `--wait-timeout <seconds>`. To return as soon as the update is accepted, use `--no-wait`. The `-o json` output also returns immediately.

When the update is accepted, the session moves to the `UPDATING` state. To see the session’s current state, run:

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

When the state leaves `UPDATING`, the session’s update record shows one of the following results.

| Result | Meaning |
|---|---|
| `APPLIED` | The change took effect without restarting the agent. |
| `APPLIED_RESTARTED` | The agent restarted to apply the change. This is the usual result for `env` and `secrets`. |
| `FAILED` | The change did not take effect. If it was reverted, the record says so and gives a reason. |

After an update, a session can differ from the environment it was created from. To see this in the session list, add the `ConfigDrifted` column with `--format`.

## Edit a Session Using the API

Send a `PATCH` request to the session with a `manifest_yaml` field that holds the partial manifest as a string:

```shell
curl -X PATCH \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"manifest_yaml": "tools:\n  - do.actions\n"}' \
  "https://api.digitalocean.com/v2/harness-runtime/sessions/<your-session-id>"
```

A change that takes effect returns `202` with the outcome `ACCEPTED` and the session in the `UPDATING` state. Poll the session every 2 to 5 seconds until its state leaves `UPDATING`, then read the update result. A request that changes nothing returns `200` with the outcome `UNCHANGED`. The request body cannot combine `manifest_yaml` with `resume_on_topoff`.

For the full request and response, see [Update a Session](https://docs.digitalocean.com/reference/api/reference/harness-runtime/index.html.md#harness_update_session) in the API reference. For Go, see the `UpdateSessionConfig` method in the [Godo](https://docs.digitalocean.com/reference/godo/reference/hosted-agents/hosted-agents-update-session-config/index.html.md) reference.

## Fix a Failed Update

| Error | Cause | What to do |
|---|---|---|
| `400` | The manifest is not valid YAML, has an unknown section, has an invalid value, or contains a top-level `model` or `permissions` section. | Fix the manifest. Only `tools`, `env`, and `secrets` can be changed. To change the model, set `HARNESS_INFERENCE_MODEL` in `env`. |
| `403` | The session belongs to another team, or your team is not enrolled in the feature. | Check the session, or contact your account team. |
| `409` | The session is paused for a zero balance, is destroyed or failed, is already updating, has a turn or approval in progress, or uses an adapter that does not support the change. The message says which. | Wait for the turn or operation to finish, top up your balance, or choose a supported change. Then retry. |
| `422` | The change needs a new session, for example a change to a scoped secret, an OAuth slot, or a platform-managed key. | Create a new session from an updated environment. |

## Related Topics

- [Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/sessions/index.html.md)
- [Secrets and Configuration](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/secrets/index.html.md)
- [Environment Spec Reference](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md)
- [Checkpoint, Fork, and Roll Back Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/checkpoint-fork-rollback-sessions/index.html.md)