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

Usage

doctl harness-runtime create [<manifest>] [flags]

Aliases

deploy, start, run

Description

Create a hosted session, wait until it is ready, optionally send --prompt, and print a ready summary. It never opens the chat — that is doctl harness-runtime launch, which is the only difference between the two commands. Open the session later with doctl harness-runtime launch <session>.

Provide exactly one of:

• a manifest — as a positional path, or with --spec / -f / --file (- reads stdin). With none of these, ./agents.yaml is used when it exists.
• --harness — opencode, claude-code, codex, or codex-agentapi (builds the manifest for you). codex is the Codex CLI, with the agent loop run by DigitalOcean; codex-agentapi is OpenAI’s sandbox-provider model, where the loop and session state live at OpenAI and DigitalOcean supplies only the sandbox (and which checkpoint, fork, and rollback do not cover).
• --from-config — an existing Agent Config, by name or ID (--name required)

These four are equivalent:

doctl harness-runtime create                       # uses ./agents.yaml
doctl harness-runtime create agents.yaml
doctl harness-runtime create -f agents.yaml
doctl harness-runtime create --spec agents.yaml

With a manifest or --harness, optionally pass --gh-repo and --prompt. Example:

doctl harness-runtime create --harness claude-code --gh-repo owner/repo --prompt "Review the README"

Flat manifests use a top-level name (or pass --name, which writes that field). Minimal example:

name: my-session
agent: opencode

Egress (optional). Omitting egress leaves destinations unrestricted. Exactly one form:

• egress: unrestricted
• host allowlist: egress: [api.github.com, pypi.org]
• object: allow_hosts, allow_ips (exact IPv4/IPv6 literals — not CIDRs), and optional vpc_uuid / subnet_uuid (subnet_uuid requires vpc_uuid; VPC attachment is create-time immutable)

egress:
  allow_hosts: [api.github.com]
  allow_ips: ["203.0.113.10"]
  vpc_uuid: <uuid>

${VAR} in a manifest is expanded from your environment (prompted in a terminal when missing). For codex and codex-agentapi, doctl prompts for $OPENAI_API_KEY when unset.

Secrets. --secret NAME=VALUE fills a secret slot the manifest declares, overriding any value written in the file — so a checked-in agents.yaml can name the credentials it needs without carrying them. NAME=@path reads the value from a file and NAME=- from stdin, neither of which leaves it in shell history. Repeat the flag per secret. For claude-code, --secret ANTHROPIC_API_KEY=@path (or =-) is enough — the key need not also be in the process environment. NAME=- cannot be combined with a manifest on stdin (--spec -). Not needed with --from-config: that config captured its values when it was created, and keeps them server-side.

Inspect before creating. --dry-run prints the fully-resolved manifest — name applied, ${VAR} expanded, secret values redacted — and exits without calling the API. That makes a working --harness invocation reusable, with no file ever touching disk:

doctl harness-runtime create --harness claude-code --gh-repo owner/repo --dry-run \
  | doctl harness-runtime config create --spec - --name reviewer --secret ANTHROPIC_API_KEY=@~/.secrets/anthropic.key

Unattended runs. --on-hitl approve|reject|defer stays attached headlessly after the session is ready — no TUI, no keyboard input, one log line per event — and resolves every approval request that way until the run finishes. Ctrl-C detaches and leaves the session running. Combined with the global --interactive=false, an agent can drive a whole run with no human present:

doctl harness-runtime create --spec agents.yaml --prompt "Fix the failing test" \
  --on-hitl approve --interactive=false

From another shell, poll with show <session> -o json, move files with upload / download, and tear down with remove (also destroy / rm).

Surviving a low balance. When a team’s prepayment balance runs out, running sessions are paused. --resume-on-topoff opts this session in to being resumed automatically once the balance is topped off, so an unattended run picks up where it stopped instead of waiting for someone to notice:

doctl harness-runtime create --spec agents.yaml --prompt "Fix the failing test" \
  --on-hitl approve --resume-on-topoff

It is off by default and is spending consent, so it is deliberately narrow: per-session (never inherited from an Agent Config, and never by a fork) and honoured only for a session paused for low balance whose last run had not finished. A session you paused yourself, or one that idled out, stays paused. It is not an agents.yaml field — pass the flag on each create, or change it later with doctl harness-runtime update <session> --resume-on-topoff[=false].

Creating from a manifest or --harness also persists an Agent Config named after the session (shown as Config on the ready card). Start later sessions from it with create --from-config or config start-session.

Use -o json for machine-readable create output without waiting. Combined with --prompt, doctl still waits until the session is ready and delivers the prompt before printing JSON — otherwise the prompt would be dropped.

Example

doctl harness-runtime create ;

Flags

Related Commands

Global Flags