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:

1{
2  "schema_version": 1,
3  "command": "non-interactive",
4  "data": {
5    "status": "success",
6    "exit_code": 0,
7    "response": "The repository contains...",
8    "completion": {
9      "thread_id": "thread-id",
10      "duration_ms": 842,
11      "response_bytes": 26
12    }
13  }
14}

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:

1{
2  "schema_version": 1,
3  "command": "tools call-read-only",
4  "data": {
5    "ok": true,
6    "status": "ok",
7    "tool": "worker_task_context",
8    "content": [],
9    "structured_content": {}
10  }
11}

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, project MCP auto-loading, startup commands, and executable hooks
  • ACP mode, interpreter tool calling, and shell allowlist overrides
  • Native LangSmith tracing and ambient OpenTelemetry exporter configuration

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 NemoClaw’s dedicated /sandbox/.deepagents/.nemoclaw-mcp.json projection 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.

Protect the Managed Login Profile

Managed Deep Agents Code images reserve /sandbox/.bash_profile as the first Bash login profile for OpenShell command sessions. The file is root:root mode 0444, and /sandbox is root:sandbox mode 1775. The sticky directory keeps normal workspace writes available while preventing the sandbox user from deleting or replacing the root-owned profile.

At each container start, the root entrypoint restores and verifies the profile before it changes to the sandbox user. If a sandbox-user start cannot verify the profile, it stops and tells you to rebuild the sandbox.

For NemoClaw-managed route and terminal probes, the profile clears BASH_ENV and ENV and skips /tmp/nemoclaw-proxy-env.sh. This prevents sandbox startup code from running before the managed probe. Ordinary login commands continue to load the credential-free runtime environment, and interactive .bashrc behavior does not change. Do not edit or replace /sandbox/.bash_profile.

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. Thread-wide auto-approval is unavailable unless you enable the managed thread opt-in capability, and shell allowlist auto-approval remains disabled.

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 activate auto-approval, but it does not activate auto-approval by itself. For each thread, select Auto-approve for this thread in the approval menu or start that dcode process with dcode -y. The TUI shows the upstream active-state indicator and a warning while the current thread can run tool calls, including shell commands, without further confirmation.

NemoClaw resets the active state when you start a new dcode process, run /clear or /force-clear, switch or resume a different thread, or switch agents. You must opt in again after each reset. 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.