{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Returns once the session row is allocated. Sandbox boot completes asynchronously.\n\nTwo mutually exclusive request forms are selected by Content-Type (same contract as\nharness-api `harness.swagger.json`):\n- YAML (`application/x-yaml`, `application/yaml`, `text/yaml`, `text/x-yaml`): the environment\n  spec. Two environment-spec formats are accepted during the dual-format transition: the flat\n  format (primary) and the legacy `agents.digitalocean.com/v1alpha1` envelope (deprecated). A\n  top-level `apiVersion` key selects the legacy parser; its absence selects flat. Internally\n  persists a durable Environment Config, then creates the session.\n- JSON (`application/json`): `{name, config_id}` loads the config, resolves its credentials from\n  Secrets Manager at the version pinned when the config was created, and creates the session.\n\nThe OpenAPI `requestBody` schemas the JSON form for client generation (Autorest cannot emit a\nmulti–content-type body). The live API still accepts the YAML forms listed above.\n\nSuccessful responses may include `config_id` on the session. `X-Device-UUID` (if present) is\npersisted on the session row. Query parameters `openai_session_id` and `resume_on_topoff` apply to\nboth forms; when both the JSON body field and `?resume_on_topoff=` are present, the query\nparameter wins.","properties":{"headers":{"type":"object","properties":{"X-Device-UUID":{"type":"string","examples":["device-uuid-example"],"description":"Optional hardware device id forwarded by doctl. Persisted on the session row for lifecycle attribution. Values over 128 bytes are ignored."}},"required":[],"additionalProperties":false},"query":{"type":"object","properties":{"openai_session_id":{"type":"string","examples":["sess_abc123"],"description":"OpenAI Agents API session id (sess_…) for adapter: codex-agentapi. doctl creates the OpenAI session before calling DO and passes the resulting id here; harness-api persists it for correlation. Empty/omitted for every other agent kind."},"resume_on_topoff":{"type":"boolean","examples":[false],"description":"Opt the new session in to automatic resumption when the team's prepayment balance is restored. Defaults to false. Exists as a query parameter so the environment spec (YAML body) form can carry it too. On the application/json form the body field is idiomatic, but this parameter wins when both are present. Must be exactly one of true/false/1/0; anything else is a 400."}},"required":[],"additionalProperties":false},"body":{"$ref":"#/definitions/create_session_config_request"}},"required":["body"],"additionalProperties":false,"definitions":{"create_session_config_request":{"type":"object","additionalProperties":false,"required":["name","config_id"],"properties":{"name":{"type":"string","minLength":1,"maxLength":64,"description":"Session name, independent of the config name. Must satisfy the existing environment-spec metadata.name rules and must not be UUID-shaped.","examples":["demo-agent"]},"config_id":{"type":"string","format":"uuid","examples":["11111111-2222-3333-4444-555555555555"]},"resume_on_topoff":{"type":"boolean","description":"Opt the new session in to automatic resumption when the team's prepayment balance is restored. Defaults to false. Session-scoped, not config-scoped: the referenced config never confers this, so one shared config cannot enrol every session created from it. Omit to leave the default (or to let the ?resume_on_topoff= query parameter supply it).","examples":[false]},"region":{"type":"string","description":"Optional placement check, not a placement choice: the session is always created in the region whose API host served the request. If set, it must equal that region, or the request fails with 400 and a region_mismatch message. Honored only for teams on the regional routing rollout; ignored otherwise.","examples":["ric1"]}},"description":"Strict application/json CreateSession form. Loads config_id, resolves the config's single internal secret binding, and creates the session. Body capped at 16 KiB; no inline secrets."}}},"name":"CreateSession provisions a sandbox and starts a Harness Runtime session.","id":"digitalocean.harness_create_session","example":{"body":{"name":"demo-agent","config_id":"11111111-2222-3333-4444-555555555555"}},"maxRequests":1,"summary":false}}