Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1160,6 +1160,15 @@ $$nemoclaw my-assistant shields down --timeout 5m --reason "maintenance"
If `shields up` reports that the config remains unlocked or drifted, confirm that the sandbox is running and ready, then retry `$$nemoclaw <name> shields up`.
If the retry still fails, rebuild a known-good baseline with `$$nemoclaw <name> rebuild --yes`.

<AgentOnly variant="deepagents">

A `CRITICAL` Deep Agents config-lock failure is not an ordinary unlocked or drifted result.
The retry and rebuild guidance above does not apply when the diagnostic includes `fail-closed containment=` or `rollback failed`.
Do not retry `shields up` or attempt an in-sandbox repair.
Follow [Deep Agents Config Lock Failure Recovery](troubleshooting#deep-agents-config-lock-failure-recovery) to restore a trusted snapshot or recreate the sandbox before retrying.

</AgentOnly>

Host-side config and inference writes, snapshot mutation, sandbox destruction, and shields transitions serialize per sandbox.
When a timed shields-down window reaches its deadline, auto-restore can interrupt the exact process tree holding that transition and restore lockdown.
Retry an interrupted command in a new shields-down window.
Expand Down
61 changes: 61 additions & 0 deletions docs/reference/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1258,6 +1258,67 @@ Run `openshell sandbox list` on the host to check the underlying sandbox state.

## Deep Agents

### Deep Agents Config Lock Failure Recovery

A `CRITICAL` Deep Agents config-lock failure reports `fail-closed containment=` or `rollback failed`.
A containment result identifies one of two confirmed postures or an incomplete containment attempt.
A `rollback failed` result does not confirm containment.
It means NemoClaw could not restore or confirm the original trusted posture.

- **Config-root posture** (`fail-closed containment=config-root`) means NemoClaw installed fresh `0444 root:root` config and hash inodes.
NemoClaw also confirmed `0500 root:root` on `/sandbox/.deepagents` and `1775 root:sandbox` on `/sandbox`.
- **Sandbox-parent posture** (`fail-closed containment=sandbox-parent`) means NemoClaw confirmed `0700 root:root` on `/sandbox` because it could not trust the config root or install and verify a fresh canonical config-and-hash pair.
- `fail-closed containment=incomplete` means NemoClaw could not confirm either complete posture.

Preserve the complete `CRITICAL` diagnostic.
Do not run `chmod`, `chown`, `shields up`, or another repair from inside the sandbox.
A confirmed containment posture deliberately removes the sandbox identity's access.
An incomplete containment result or `rollback failed` does not establish a trustworthy boundary from which to accept the current bytes.
An ordinary `rebuild` cannot turn the current state into a trustworthy snapshot.

If you have a trusted host-side snapshot from before the failure, list the snapshots and record its selector:

```bash
$$nemoclaw <name> snapshot list
```

<Warning>
Destroying the sandbox permanently discards state newer than the selected snapshot.
Confirm that the trusted host-side snapshot exists before you destroy the sandbox.
</Warning>

Destroy the sandbox, re-onboard the same name from trusted host configuration, and restore the snapshot:

```bash
$$nemoclaw <name> destroy
$$nemoclaw onboard --name <name> --agent dcode
$$nemoclaw <name> snapshot restore <selector>
```

For snapshot contents and selector rules, refer to [Create and Restore Snapshots](../manage-sandboxes/state-and-backups/create-and-restore-snapshots).

If no trusted snapshot exists and you do not need to preserve the current state, recreate the sandbox from host-side onboarding configuration.

<Warning>
This recreation permanently discards the current sandbox state.
Continue only if you accept that loss.
</Warning>

```bash
$$nemoclaw <name> destroy
$$nemoclaw onboard --name <name> --agent dcode
```

After either recovery path, verify the recreated sandbox from the host:

```bash
$$nemoclaw <name> status
$$nemoclaw <name> shields status
```

Continue only when `status` identifies the expected Deep Agents sandbox and `shields status` returns without a `CRITICAL` or corrupt-state diagnostic.
Then retry the original `shields up` operation.

### `dcode status` reports a stale inference route

The managed `dcode` runtime reads provider and model settings from `/sandbox/.deepagents/config.toml`.
Expand Down
Loading
Loading