How to Update the Settings of a DigitalOcean Harness Runtime Sessionpublic

Last verified 20 Nov 2026

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 for example use cases.

A session starts with the settings of the environment 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 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.

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.
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:

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

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

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

You can also read the manifest from standard input:

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

For the fields a tool entry accepts, see 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:

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 for how the token is declared.

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

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:

secrets:
  OPENAI_API_KEY: {}
  GITHUB_TOKEN: ${GITHUB_TOKEN}

Apply it:

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.

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:

env:
  FEATURE_FLAG: "on"
  LOG_LEVEL: debug

Apply it the same way:

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. 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:

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

Apply it:

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:

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:

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 in the API reference. For Go, see the UpdateSessionConfig method in the Godo 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.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.