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

Connect to the sandbox, then launch the terminal UI:

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

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

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.

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 exact registry-owned legacy entries without claiming unrelated user content. Before launch, NemoClaw validates and canonicalizes the complete managed file as HTTPS-only definitions with exact 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.

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.