doctl harness-runtime launch

Generated on 1 Oct 2026 from doctl version v1.177.0

Copy page as Markdown View page as Markdown

Usage 

doctl harness-runtime launch [<session>|<manifest>] [flags]

Aliases 

up, chat, attach

Description

Open an interactive chat on a session, creating it first when you give it something to create from. Aliases: up, chat, attach.

Attach to a session that exists. Pass its name or ID and nothing else:

doctl harness-runtime launch my-session
doctl harness-runtime launch sess_abc123

A paused session is resumed on the way in, so waking one up and looking at it is a single command. A destroyed or failed session is an error rather than something to resume.

Create a session, then attach. Pass a manifest, --harness, or --from-config — every creation flag works exactly as it does on doctl harness-runtime create:

doctl harness-runtime launch                       # uses ./agents.yaml
doctl harness-runtime launch agents.yaml
doctl harness-runtime launch --harness opencode --gh-repo owner/repo --prompt "Review the README"
doctl harness-runtime launch --from-config reviewer --name my-session

How the positional argument is read. One rule: does a readable file exist at that path? If yes it is a manifest and a new session is created; if no it is treated as a session name or ID. An argument that is neither reports both possibilities. Naming a creation flag settles it without consulting the filesystem.

Type messages and press Enter. Ctrl-C cancels the turn in progress and leaves the session ready for the next message; so does Esc on an empty prompt (Esc with text typed clears the text first). Agents that cannot cancel a turn say so. Ctrl-D detaches without removing the session, and so does Ctrl-C when no turn is running or once a cancel has been sent — reattach later, or run doctl harness-runtime remove to tear it down. If the connection drops, doctl reconnects automatically. For OpenAI sandbox sessions, doctl prompts for $OPENAI_API_KEY when it is unset.

When approval is required: y/a approve, n/r reject, d defer. Type /help for slash commands. To resolve approvals with no human at all, see doctl harness-runtime create --on-hitl.

This command always ends in a terminal chat, so it has no -o json form and needs a TTY; use doctl harness-runtime create in scripts and pipelines. For the native Codex desktop/CLI UI instead of doctl chat, see doctl harness-runtime start-proxy --help.

Example 

doctl harness-runtime launch my-session;

Flags

Option Description
--dry-run Create-only; use doctl harness-runtime create –dry-run
Default: false
--from-config Name or ID of an existing Agent Config to create the session from. Requires –name. Mutually exclusive with –harness and –spec.
--gh-repo GitHub repository to clone into the workspace (https://github.com/org/repo or org/repo). Only with –harness or –spec.
--harness Coding-agent harness (opencode, claude-code, codex, codex-agentapi). Builds the manifest for you. codex is the Codex CLI run by DigitalOcean; codex-agentapi is OpenAI’s sandbox-provider model, where OpenAI runs the agent loop. Omit it and pass –template sandbox for a sandbox with no agent in it, which you drive with exec, upload, download and port-forward. Mutually exclusive with –spec and –from-config.
--help, -h Help for this command
--name Name for the new session. On flat manifests sets top-level name; on legacy envelopes sets metadata.name. If omitted, the server auto-generates a name. Must be unique among your team’s active sessions. Required with –from-config.
--on-hitl Create-only; use doctl harness-runtime create –on-hitl
--permission Tool-permission default for a –harness session: allow (run tools without asking), ask (raise an approval request per tool call, resolvable with ‘doctl harness-runtime approve’), or deny. Written as the manifest’s permissions.default. Only valid with –harness; a –spec manifest declares its own.
Default: allow
--prompt Initial prompt to send once the session is ready
--resume-on-topoff Let DigitalOcean resume this session automatically once your team’s prepayment balance is topped off after a low-balance pause. Off by default and per-session (never inherited from an Agent Config or by a fork). Revoke it with –resume-on-topoff=false. Only a session paused for low balance whose last run was unfinished is resumed; one you paused yourself, or that idled out, stays paused.
Default: false
--secret Tenant secret as NAME=VALUE, injected into the manifest’s secret slots (overriding a value declared in the file). Repeatable. NAME=@path reads the value from a file and NAME=- reads it from stdin, so a credential need not appear in shell history or in checked-in YAML.
--spec, -f Path to an agent manifest in YAML or JSON, equivalently given as a positional argument or –file. Defaults to ./agents.yaml when present. Prefer flat format (top-level name + agent), e.g. “name: my-session\nagent: opencode”. Legacy apiVersion/kind/metadata/spec envelopes still work. Set to “-” to read from stdin. ${VAR} references are resolved from the local environment. Mutually exclusive with –harness and –from-config.
--template Sandbox template the session runs on. Either a platform template (sandbox for a bare sandbox, or the template that matches your –harness) or one of your team’s own from ‘doctl harness-runtime template create’ — a team template of the same name takes precedence. Omit it to get the default for the chosen –harness. Passed without –harness it asks for a sandbox with no agent in it. A –spec manifest sets its own top-level template.
--wait-timeout Maximum seconds to wait for the session to become ready (0 uses the default). Ignored with -o json unless –prompt is also set.
Default: 300
Command Description
doctl harness-runtime Managed Agents Runtime Services (M.A.R.S)

Global Flags

Option Description
--access-token, -t API V2 access token
--api-url, -u Override default API endpoint
--config, -c Specify a custom config file
Default:
    --context Specify a custom authentication context name
    --http-retry-max Set maximum number of retries for requests that fail with a 429 or 500-level error
    Default: 5
    --http-retry-wait-max Set the minimum number of seconds to wait before retrying a failed request
    Default: 30
    --http-retry-wait-min Set the maximum number of seconds to wait before retrying a failed request
    Default: 1
    --interactive Enable interactive behavior. Defaults to true if the terminal supports it (default false)
    Default: false
    --output, -o Desired output format [text|json]
    Default: text
    --trace Show a log of network activity while performing a command
    Default: false
    --verbose, -v Enable verbose output
    Default: false

    We can't find any results for your search.

    Try using different keywords or simplifying your search terms.