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

client.v2.agents.sessions.policy.validate.post(body: undefined | ArrayBuffer, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | Validation_result>

Description

Stateless preflight: parses the same environment spec as CreateSession and runs the identical resolve + validate pipeline against the capability descriptor stamped on the selected template’s image (resolved per-request via the sandbox, not a separate registry). Returns per-rule verdicts. Nothing is provisioned or persisted.

Each rule is validated against the descriptor for the (agent, version) the template resolves to and gets a verdict: exact, degraded, unsupported, or unverified. ok is false when any strict rule is unsupported or unverified, i.e. CreateSession would reject the policy for that agent. An empty spec.permissions returns ok: true with no verdicts. Because it shares the create path’s descriptor lookup, the verdicts match what CreateSession would compute.

Parameters

The request body uses application/x-yaml.

apiVersion string optional

Example: agents.digitalocean.com/v1alpha1

Legacy envelope only - must be "agents.digitalocean.com/v1alpha1", and its presence is what routes the document to the deprecated legacy parser. Flat-format manifests carry no version key (the endpoint owns the contract); required, with kind and spec, when authoring the legacy format.

kind string optional

Example: Agent

Must be "Agent".

metadata object optional

Show child properties

name string optional

Example: example

Optional team-unique session name: 1-64 chars of letters, digits, '-', '.', '_', starting and ending alphanumeric; case-insensitive; must not be UUID-shaped. Omit to have the control plane generate one ("session-<agent-type>-<date-time>"). Unique among the team's ACTIVE (non-terminal) sessions; destroying a session frees its name for reuse.

description string optional

Example: Use when ...

Free-form description (max 1024 chars), stored and echoed back for Console / catalog surfaces.

labels object optional

Example: {}

spec object optional

Show child properties

permissions object optional

Customer-declared tool-execution permission policy (spec.permissions). REQUEST only: the policy engine resolves it (∩ tenant ∩ platform) into the canonical policy and validates it against the (agent, version) capability descriptor. Absent or empty means the agent keeps its built-in default gating, no policy is shipped to the sandbox.

Show child properties

defaultAction string optional

Disposition for tool calls that match no rule. Defaults to "ask" when omitted.

One of: allow, ask, deny

rules array of objects optional

Ordered match→action rules. Declared order is authoritative: the LAST matching rule wins (author-order last-match).

Show child properties

tool string required

Example: example

Tool taxonomy this rule matches (e.g. bash, file.read, file.write, web.fetch, git.*, mcp).

match object optional

Optional keys narrowing the rule (e.g. {"command": "npm run deploy"} for bash). Values are globs and must not contain shell-style ${VAR}/$VAR expansions.

action string required

One of: allow, ask, deny

enforcement string optional

What happens when the agent cannot enforce the rule exactly. "strict" rejects the session; "best-effort" degrades to the closest more-restrictive form and warns (never widens). Defaults to strict for deny rules, best-effort otherwise.

One of: strict, best-effort

filesystem object optional

Filesystem boundary, enforced by the microVM (read-only root + bind-mounted writable roots) for every agent.

Show child properties

mode string optional

One of: read-only, workspace-write

allowWrite array of strings optional

Example: ["example"]

Additional writable paths beyond the workspace. Values must not contain shell-style ${VAR}/$VAR expansions.

network object optional

Network boundary. Narrows (subtract-only) spec.sandbox.egress; link-local/internal addresses stay blocked by the broader egress policy.

Show child properties

defaultEscaped string optional

One of: allow, deny

allow array of strings optional

Example: ["example"]

mode string optional

Explicit lifecycle discriminator. Defaults to "interactive" (spec.serving forbidden); "served" requires spec.serving.

One of: interactive, served

runtime object required

Canonical adapter ids: claude-code | opencode | codex | cursor | hermes | codex-agentapi | custom. codex-agentapi is the OpenAI sandbox-provider runtime (DO runs codex exec-server; the agent loop lives at OpenAI) and pairs with the opaque spec.runtime.config block. codex-cli and cursor-cli are deprecated aliases (accepted with a create-time warning). The framework adapters (openai-agents, claude-agent-sdk, crewai, langgraph) are declared but not yet supported; CreateSession rejects them. adapter: custom requires the custom block.

Additional nested properties are not shown.

workspace object optional

Repositories the session works against.

Additional nested properties are not shown.

sandbox object optional

Additional nested properties are not shown.

model object optional

Accepted, not yet enforced (returns a warning). Model routing (Plano); catalog-validated when enforcement lands.

Additional nested properties are not shown.

tools object optional

Accepted, not yet enforced (returns a warning). Exactly one of mcpServers or bundle.

Additional nested properties are not shown.

skills array of objects optional

Inline agent skills (SKILL.md shape): reusable markdown instructions the agent loads on demand, selected by description. Accepted, not yet enforced (returns a warning). Max 32 entries; instructions additionally capped at 256 KiB summed across the list so a valid manifest always fits the request-body limits. v0 is inline-only - remote skill sources come later as an additive field.

Additional nested properties are not shown.

env object optional

Example: {}

Non-secret guest env (debug-readable - never put secrets here; use spec.secrets). Reserved platform keys (TEAM_ID, SESSION_ID, SANDBOX_ID, CONTROL_PLANE_CALLBACK_URL, SANDBOX_TEMPLATE, SANDBOX_AGENT_WORKDIR, SIZE_SLUG, SANDBOX_IMAGE_ID, SANDBOX_OCI_REF, PLANO_PERMISSION_*) are rejected. Credential-looking values (dop_v1_..., sk-..., ghp_...) trigger a create-time warning.

memory object optional

Accepted, not yet enforced (returns a warning).

Additional nested properties are not shown.

secrets array of objects optional

Declared credential requirements. source tenantSecret is enforced today: value is write-only plaintext, extracted into Secrets Manager at create and never persisted or returned. source oauth requires provider, carries no value, and is accepted but not yet enforced. ref is legacy and ignored. env false keeps the resolved value out of the guest environment (mount-only slots).

Additional nested properties are not shown.

defaults object optional

Additional nested properties are not shown.

serving object optional

Present only when spec.mode is "served" (autoscaled fleet).

Additional nested properties are not shown.

Response Example

{
  "agent": "example",
  "version": "example",
  "ok": true,
  "defaultAction": "allow",
  "defaultActionVerdict": "exact",
  "defaultActionRendered": "allow",
  "defaultActionReason": "example",
  "verdicts": [
    {
      "verdict": "exact",
      "rendered": "allow",
      "reason": "example",
      "suggestion": "example"
    }
  ]
}

More Information

See /v2/agents/sessions/policy/validate in the API reference for additional detail on responses, headers, parameters, and more.