Manage SandboxesOperate Sandboxes

Run LangChain Deep Agents Code

View as Markdown

Use the managed dcode launchers to run interactive or headless work inside an existing Deep Agents Code sandbox. Complete Quickstart with Deep Agents before you use these operating workflows.

Choose the Default Sandbox

When you manage multiple sandboxes, use the Deep Agents alias to promote a registered Deep Agents Code sandbox to the default:

nemo-deepagents use <sandbox-name>

The command updates NemoClaw’s host-side registry. It does not modify the sandbox or the dcode configuration.

Run Interactive or Headless Tasks

Start the terminal UI from the host:

nemo-deepagents launch <sandbox-name>

To open a sandbox shell first, connect and then start the terminal UI yourself:

nemo-deepagents <sandbox-name> connect
dcode

Headless dcode -n has no approval UI and automatically approves non-shell tool requests, including file writes and edits. Use the interactive TUI when you need to inspect each destructive tool request before it runs.

Run the headless commands from a sandbox shell that you open with nemo-deepagents <sandbox-name> connect. dcode is an in-sandbox binary and is not on the host PATH.

For a single headless task, run:

dcode -n "Summarize this repository"

For automation, add --json:

dcode -n "Summarize this repository" --json

The managed runtime writes exactly one UTF-8 JSON object to stdout and suppresses progress and other stdout text. Warnings and diagnostics go to stderr. A successful run has this version 1 envelope:

{
  "schema_version": 1,
  "command": "non-interactive",
  "data": {
    "status": "success",
    "exit_code": 0,
    "response": "The repository contains...",
    "completion": {
      "thread_id": "thread-id",
      "duration_ms": 842,
      "response_bytes": 26
    }
  }
}

response contains the final assistant text on success and is null on failure. response_bytes is its UTF-8 byte length on success and is 0 on failure. The process exit code matches data.exit_code. The terminal statuses are success, agent_failure, process_failure, timeout, turn_limit, cancelled, and output_limit. A timeout exits 124, cancellation exits 130, and other failures exit nonzero.

When a headless run fails, the managed runtime classifies the active client exception chain when it contains a pinned exception class. Known classifications cover LangGraph SDK request failures, transport and TLS failures, and managed model-configuration failures. The stderr diagnostic includes error_class, category, retryable, and correlation_id. Use correlation_id to match the failure to logs. The retryable field is diagnostic information and does not cause an automatic retry.

The runtime does not classify persisted checkpoint exception text. If no pinned exception class matches, stderr reports error_class=unknown category=unknown retryable=false. Text mode also prints Unexpected error with only the correlation ID. The runtime emits only fixed classification labels and does not copy the exception class name, message, or checkpoint content.

The complete serialized envelope is limited to 1 MiB. If the response cannot fit, the runtime discards it and emits a bounded output_limit failure envelope. If it cannot write the envelope, the command exits nonzero and reports the write failure on stderr. Callers must reject empty, malformed, additional, or unsupported-version stdout.

Call a Read-Only MCP Tool

Use dcode tools call-read-only when automation must invoke one managed MCP tool without model participation. The command accepts one tool name, requires --json, and reads one JSON object from standard input.

printf '%s\n' '{"worker":"worker-17","nonce":"request-42"}' | \
  dcode tools call-read-only worker_task_context --json

The command reads standard input to end-of-file and requires one UTF-8 JSON object of at most 131,072 bytes. It rejects terminal input, empty input, duplicate object keys, non-object JSON, non-finite constants, malformed UTF-8, and additional JSON values.

The command loads only MCP servers registered through NemoClaw. The tool name must contain 1 to 128 ASCII letters, digits, underscores, or hyphens, and its first character must be alphanumeric. It must resolve once, identify an MCP tool, and pass the managed coherent read-only annotation check. A prompt, agent, or model does not select the tool, modify its arguments, or participate in the call. Unavailable, ambiguous, non-MCP, and mutating tools fail before invocation.

For the fixed call form, standard output contains exactly one version 1 JSON envelope followed by a newline unless the write itself fails. dcode tools call-read-only --help is the exception: it prints plain usage and exits 0. A successful call has this shape:

{
  "schema_version": 1,
  "command": "tools call-read-only",
  "data": {
    "ok": true,
    "status": "ok",
    "tool": "worker_task_context",
    "content": [],
    "structured_content": {}
  }
}

content preserves the successful MCP ToolMessage content. structured_content appears only when the server returns an artifact that contains only a structured_content mapping. A tool-reported failure, unsupported result type, malformed artifact, non-finite value, cyclic value, non-string object key, or another container at depth 64 fails closed. A primitive value at depth 64 is accepted. There is no separate string-length or item-count limit. The input, successful result before redaction, and final serialized envelope each have a 131,072-byte bound. NemoClaw applies best-effort redaction for recognized credential-shaped values in successful content and structured_content without changing the JSON structure. This redaction does not guarantee detection of a secret embedded in ordinary content.

Errors use the same envelope with a bounded data object containing ok: false, status: "error", code, and message. Command-shape and tool-name errors exit 2. A successful call exits 0, an interrupt exits 130, and all managed input, discovery, eligibility, invocation, result, timeout, cleanup, or runtime failures exit 1. The process exit code is the result authority; automation must reject empty, malformed, additional, or unsupported-version stdout.

Discovery, invocation, and normal manager cleanup share a 15-second deadline. After that deadline, NemoClaw cancels the task and waits up to 3 seconds for that task, including its cleanup. It then cancels other pending event-loop tasks and waits up to 0.1 seconds before closing the loop and emitting the fixed timeout error. The managed dcode wrapper suppresses Python, MCP child, logging, traceback, and write-failure diagnostics on stderr. A stdout write failure can therefore exit without a complete envelope and with no stderr diagnostic.

This command uses only MCP servers registered through NemoClaw. For MCP registration and credential lifecycle operations, refer to Add an MCP Server and Manage MCP Servers.

Understand the Managed Runtime

The managed dcode, dcode.real, and deepagents-code launchers use /opt/venv/bin/python3 -I to run the pinned package with an isolated import path and HOME=/sandbox. For interactive and headless sessions, each launcher supervises its own process descendants. Completion, terminal exit, or disconnect terminates the associated LangGraph server tree without affecting another session. After a disconnect, the supervisor uses bounded grace periods before it kills unresponsive processes from that session. The supervisor runs inside the Linux OpenShell sandbox and fails closed if invoked outside Linux; the host operating system does not change this sandbox guarantee.

The managed launchers disable the following mutable or unsupported behavior:

  • Deep Agents Code package update checks and the LangGraph server version check
  • CLI and TUI update or install commands
  • Nested remote sandbox providers and remote asynchronous subagents
  • Deep Agents Model Context Protocol (MCP) commands and project MCP auto-loading
  • ACP mode
  • Native LangSmith tracing and ambient OpenTelemetry exporter configuration

Interactive sessions retain Deep Agents Code’s native local behavior for shell allowlists, startup commands, interpreter and programmatic-tool settings, and user hooks. These processes run as the sandbox user inside OpenShell and receive the supported secret-free runtime environment. NemoClaw snapshots and restores hooks.json plus the supported interpreter and startup-mode keys in config.toml during a managed rebuild.

The managed model constructor accepts only Deep Agents Code’s openai provider path and reads its endpoint from a root-owned image file. It supplies the non-secret gateway placeholder key and ignores mutable provider classes, credentials, endpoints, and constructor parameters in Deep Agents Code config. CLI and TUI model parameter overrides and custom rubric models are blocked. For headless runs, --max-retries remains available after Deep Agents Code validates the retry count. The managed boundary discards every other model parameter, including credentials, endpoints, and provider settings. Project and user-defined subagents remain available, but they inherit the managed chat model instead of accepting their own model override.

MCP servers registered through nemo-deepagents <sandbox-name> mcp add remain available through the agent-native /sandbox/.deepagents/.mcp.json configuration and OpenShell egress policy. Project and user MCP files are never auto-loaded. Sandboxes with the older managed MCP v1 runtime must rebuild before mcp add or mcp restart. Remove, rebuild, and destroy can still scrub registry-owned legacy entries without claiming unrelated user content. Before launch, NemoClaw validates and canonicalizes the complete managed file as HTTPS-only definitions with OpenShell credential placeholders. It then gives Deep Agents Code a process-local, integrity-bound snapshot for server starts and restarts. It prefers a sealed in-memory file when available. The OpenShell-compatible anonymous read-only descriptor fallback verifies the inode, size, and SHA-256 digest and fails closed on drift. Stdio commands, extra headers, raw credentials, and unrelated top-level configuration fail closed. For authenticated MCP setup and credential rotation, refer to Add an MCP Server and Manage MCP Servers. This isolated-mode guarantee applies to the managed launchers, not arbitrary Python commands in the sandbox.

Edit Personal Shell Files

You can edit personal shell files under /sandbox, including .bashrc, .profile, and .bash_profile. Ordinary login and interactive shells use your personal files.

Managed probes use /etc/profile.d/nemoclaw-dcode.sh, owned by root:root with mode 0444. The hook clears BASH_ENV and ENV and selects an image-owned home before Bash reads personal files. The managed launcher restores HOME=/sandbox and reads proxy settings from image-owned files.

Existing Deep Agents Code sandboxes retain their previous image until you rebuild them. After you update NemoClaw, finish active tasks and follow Recover and Rebuild Sandboxes to replace each image.

Choose an Approval Boundary

Interactive shell execution and other destructive tools remain behind human-in-the-loop approval prompts by default. Automatic and unrestricted approval modes remain unavailable unless you enable the managed thread opt-in capability. Interactive shell allowlists use Deep Agents Code’s native approval behavior.

Headless dcode -n is an explicit automation boundary. The managed headless path still disables shell execution, startup commands, interpreter tool calling, executable hooks, unmanaged MCP configuration, nested remote sandboxes, remote asynchronous subagents, and alternate model routes.

Configure Thread Auto-Approval

Managed Deep Agents sandboxes keep interactive thread auto-approval disabled by default. In this mode, the TUI auto-approval choice and dcode -y fail closed.

Enable the capability for a named sandbox through a transactional rebuild because NemoClaw bakes the capability into the managed image:

nemo-deepagents <sandbox-name> rebuild --dcode-auto-approval thread-opt-in --yes

The thread-opt-in setting grants permission to use Deep Agents Code’s native approval modes, but it does not activate one by itself. Use dcode -y or Enable Auto for this thread for classifier-backed Auto mode. Use the native --yolo or /yolo path for unrestricted approval after its warning and acknowledgement. The TUI shows the upstream active-state indicator for the selected mode.

Deep Agents Code preserves its native approval state across /clear, /force-clear, thread resume or switch, and agent switch operations. A new process starts from the native [startup].mode setting; NemoClaw forces Manual when the sandbox capability is disabled. The host-side status command reports the configured capability, not whether one live TUI thread currently has auto-approval active:

nemo-deepagents <sandbox-name> status

Thread auto-approval does not bypass OpenShell network policy, credential isolation, the managed inference route, managed MCP validation, or the other Deep Agents runtime restrictions. Headless dcode -n remains a separate automation boundary with non-shell auto-approval and managed shell execution disabled.

Return the sandbox to the default posture with another transactional rebuild:

nemo-deepagents <sandbox-name> rebuild --dcode-auto-approval disabled --yes

Inspect Runtime Identity and Configuration

To confirm which sandbox a session is in, run:

dcode status

The command prints the sandbox name, NemoClaw harness, active dcode agent, configured inference route, upstream provider, model, endpoint, and runtime. It then exits without starting the interactive UI. dcode whoami and dcode identity are aliases. dcode --help lists the managed aliases before the upstream Deep Agents Code help. The sandbox name resolves when you run the command from a nemo-deepagents <sandbox-name> connect shell, which loads the NemoClaw runtime environment.

Inspect the generated Deep Agents configuration from the host:

nemo-deepagents <sandbox-name> config get

NemoClaw parses config.toml, removes gateway auth data, and redacts credential-shaped values before printing it. config set is not supported for this image-baked configuration. Re-onboard the named sandbox to change its managed provider or model selection.