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

As an alternative to configuring your environment in the Control Panel, you can define an environment specification using YAML.

Field names are decoded strictly. An unknown or misspelled field returns a 400 naming the key, so nothing you write is silently ignored.

Example Environment Specification

The following spec shows a named Codex session with size and idle timeout, a persistent workspace, env and secrets, an egress allowlist, Action Gateway and custom MCP tools, inline skills, permission rules, and interactive mode.

name: my-first-session
agent: codex
size: mars-2vcpu-4gb
idle_timeout: 10m
persistent_workspace: true
env:
  MODEL: gpt-5.4
secrets:
  OPENAI_API_KEY: ${OPENAI_API_KEY}
egress:
  - api.github.com
  - pypi.org
  - mcp.example.com        # inline MCP hosts are NOT auto-allowed
tools:
  # One entry per server. `- do.actions` (all tools) OR `- do.actions: [...]`
  # (selection). Declaring both is a duplicate-server 400.
  - do.actions: [exa_web_search, action_code, "toolbelt:read-only@1"]
  - name: my-mcp
    url: https://mcp.example.com
    tools: [search, fetch]
    auth:
      header: Authorization
      secret: MY_MCP_TOKEN
skills:
  - name: pdf-processing
    description: "Use when the task involves reading or editing PDF files."
    instructions: |
      # PDF Processing
      Steps the agent should follow...
    license: Apache-2.0
    metadata:
      author: platform-team
    allowed_tools: [file.read, bash]
permissions:
  default: ask
  rules:
    - tool: bash
      action: ask
      enforcement: strict          # strict | best-effort
    - tool: file.read
      action: allow
    # Server-qualified MCP targets; server must be declared in `tools`.
    - tool: do.actions/exa_web_search
      action: allow
    - tool: my-mcp/create_issue
      action: ask
mode: interactive

Top-Level Fields

The environment specification has the following top-level fields.

Durations are strings of integer hour, minute, or second components (10m, 90s, 8h, 1h30m). Bare second counts such as 600 are not allowed.

agent

The agent field accepts the following adapter identifiers. For the architectural difference between them, see Agent Adapters.

The deprecated alias codex-cli is still accepted and resolves to codex, with a warning.

config for codex-agentapi

Use config only with agent: codex-agentapi. DigitalOcean forwards it as the OpenAI Agents API create-session body, stores and echoes it, and does not validate its contents.

CLI and webhook-managed spec

Include the OpenAI create-session request in config. The CLI authenticates that request with OPENAI_API_KEY, fills ${ENV_ID} from the response, and injects the executor key as CODEX_API_KEY:

name: openai-codex-session
agent: codex-agentapi
config:
  agent:
    model: gpt-5.6-sol
    instructions: Work from the files in /workspace.
  environment:
    type: self_hosted
    workspace_directory: /workspace
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

Application-managed spec

When the application creates the OpenAI session first, omit config from the sandbox-only spec:

agent: codex-agentapi
egress:
  - api.openai.com
  - codex-cloud-environments.chatgpt.com
env:
  CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
  CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}

Pass the OpenAI session ID in params.openai_session_id and supply ENV_ID and OPENAI_EXECUTOR_API_KEY through body.variables when calling client.agents.create_session.

Provider-specific fields

Use OPENAI_API_KEY for OpenAI API requests made by the application, controller, or CLI. Use a separate OPENAI_EXECUTOR_API_KEY environment key for the executor connection. Both keys must have the same owner, organization, and project. Place the executor key under secrets, not env, and do not log or save the resolved manifest. See Secrets and Configuration.

mode and serving

mode is the lifecycle discriminator.

When mode: served, the serving object takes the following fields.

keep_warm

keep_warm: true exempts a session from idle auto-pause entirely. It exists because idle_timeout cannot express “never”: omitting it means “use the team default” and 0 means the same, so no duration disables the timer.

Declaring both idle_timeout and keep_warm is rejected rather than resolved in favor of one, because the timeout would otherwise silently never elapse.

Omitting keep_warm leaves the choice to the adapter. Adapters whose value is an always-available interactive surface default to staying warm, such as hermes, whose dashboard is reachable through port forwarding only while the sandbox runs. Every other adapter defaults to pausing on idle. Setting keep_warm: false opts a hermes session back into pausing.

A warm session bills for its sandbox until you stop it explicitly, and a request to pause one returns a 409. The policy applies to manual pause as well as the automatic path.

agent: hermes
keep_warm: true

egress

egress requests the session’s outbound network policy. Omitting it leaves the session unrestricted. Setting an allowlist turns it on, and everything unnamed is then denied. The field takes exactly one of the following forms.

The object form takes the following fields.

When the allowlist is on, the platform merges in the hosts the session needs to function: platform hosts such as api.github.com, github.com, and registry.digitalocean.com, the hosts the adapter requires, and the configured model inference endpoints. Omitting egress adds none of these, because there is no allowlist to add to. An allowlist built only from allow_ips also does not receive them, and session creation returns a warning in that case.

The request is not the final policy. The platform intersects it with team and platform policy, which can narrow what you ask for but never widens it.

Inline MCP hosts are not reliably added to the allowlist. List them under egress as well. Tools reached through Action Gateway need no entry, because the gateway calls the provider rather than the sandbox doing so. For the wider model, see Network Egress.

env

Non-secret plaintext config merged into the guest environment. The guest environment is debug-readable, so use secrets for credentials.

secrets

Every credential the agent needs, declared in one map. The slot name is the guest environment variable. doctl expands ${VAR} placeholders client-side before upload, and an unexpanded ${VAR} or $VAR value is rejected.

secrets:
  OPENAI_API_KEY: ${OPENAI_API_KEY}
  DATASETS_ACCESS_KEY:
    value: ${SPACES_ACCESS_KEY}
    env: false
  DATASETS_SECRET_KEY:
    value: ${SPACES_SECRET_KEY}
    env: false

A slot value takes one of the following forms.

The object form takes the following fields.

secrets:
  PROVIDER_API_KEY:
    value: ${PROVIDER_API_KEY}
    url: https://api.example.com

url accepts https:// with one exact hostname and no port, query, fragment, or embedded credentials. Wildcards, IP literals, localhost, and metadata addresses are rejected, and a hostname matches only itself rather than its subdomains. A path is optional, is treated as a prefix, must start with /, must stay under 256 characters, and cannot contain ?, #, or %.

An environment can declare at most 16 scoped secrets. A slot cannot combine url with env: false, because the handle has to reach the guest environment. The bound host is added to the egress allowlist automatically.

Redemption depends on infrastructure support that is not yet enabled everywhere. Where it is missing, the sandbox still receives a handle rather than the credential, and requests to the bound host fail to authenticate. See Secrets and Configuration.

For guidance on choosing between env and secrets, see Secrets and Configuration.

permissions

The permission policy for the environment. It applies when the session starts and is checked against what the chosen adapter supports. If you omit permissions, the platform uses its built-in default. For native Harness Runtime actions, the last matching rule in the list wins, and if no rule matches, the action uses default.

A rule naming a tool the adapter does not declare is not silently ignored. Under the default strict enforcement a deny or ask rule on an undeclared tool fails session create, while an allow rule degrades to a warning. This matters most with codex, which declares only bash. Two parts of the taxonomy are currently declared by no adapter at all, so a rule naming them can only ever warn or block: git.* and web.fetch. Set enforcement: best-effort on a rule you want downgraded to a warning rather than treated as a create-time error.

Action Gateway evaluates its projected tool rules separately, using most-specific matching rather than list order. An ask decision there requires the client to complete MCP elicitation or a separate approval request, so do not assume every adapter supports an inline prompt. See Permission Policies and Action Gateway Tool Policies.

tools

Requests MCP server attachments. Each list entry is exactly one of two forms.

An inline entry takes the following fields.

tools:
  - do.actions: [exa_web_search, action_code, toolbelt:read-only@1]
  - name: internal-jira
    url: https://mcp.example.com/mcp
    tools: [create_issue]
    auth:
      header: Authorization
      secret: JIRA_MCP_TOKEN

Attaching a tool does not grant permission to call it. Allow, ask, and deny dispositions stay in permissions. See Connect Action Gateway to Harness Runtime.

skills

Inline agent skills in the Agent Skills (SKILL.md) shape. A spec accepts a maximum of 32 entries. instructions are capped at 32 KiB per skill and 256 KiB total across the list, and the encoded guest environment value must also fit the 64 KiB variable cap. workspace-repos and sandbox-access are platform-reserved names.