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.
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.
Prerequisites
- A session that uses the Claude Code, OpenCode, Codex, Hermes, or LangGraph adapter. Sessions that use other adapters return a
409error. - 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.
doctlinstalled 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:
toolsis the full replacement list. Every tool or MCP server you leave out of the list is detached.tools: []detaches all of them.envis a full set. A key you leave out is removed.secretsis a full set. A key you leave out is removed. A string value sets or rotates the secret, and{}keeps its current value.
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.yamlYou can also read the manifest from standard input:
doctl harness-runtime update <your-session-name> --file - < tools.yamlFor 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.yamlThe 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: debugApply it the same way:
doctl harness-runtime update <your-session-name> --spec env.yamlThe 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.yamlThis 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. |