Recovery

Agent recovery reverses writes made by a selected agent after a specified time. Later work by other users or agents is preserved. Recovery uses the agent’s durable identity across all of its runtime tokens.

Multi-Agent Undo Demo

This demo uses the dbx CLI to create a managed user and two agent workspaces, inspect each agent’s file changes, and undo one agent’s video edits while preserving the user’s and the other agent’s work.

Before you begin

Use the owning user’s token through the same app that created the agent. Apps created through Application Setup are configured for recovery.

You should stop writes from the agent before starting recovery and keep them stopped until undo completes. For a CLI mount, dbx mount stop stops writes through the mount and flushes pending changes. Recovery does not stop mounts or revoke runtime tokens.

Inspect an agent’s mutations

To review what an agent changed, list its retained mutations with the owning user’s profile or the agents/mutations/list API endpoint:

dbx agent mutations build-agent --profile standalone-user

The list is newest first and covers the agent’s runtime tokens. Text output shows TIMESTAMP_UTC, TIMESTAMP_US, OPERATION, and DETAILS. TIMESTAMP_UTC is a readable RFC3339 timestamp in UTC. Details contain a file or folder path, or both locations for a move or rename. A folder move, rename, or deletion appears as one mutation, without separate entries for its contents. History is limited by retention and the user’s current access.

By default, the command fetches one page with a requested limit of 100. Pass the returned next_cursor to continue, or use --all to fetch every remaining page:

dbx agent mutations build-agent \
  --cursor "$NEXT_CURSOR" \
  --profile standalone-user
dbx agent mutations build-agent \
  --all --output=json \
  --profile standalone-user

--limit accepts 1 through 1000, but a page can exceed the requested size. Cursors expire after 24 hours. JSON output keeps each mutation’s metadata and Unix microsecond timestamp_us in result.mutations; the next cursor is in result.next_cursor when another page is available.

Choose a timestamp from the mutation history that includes the changes you want to revert. Use its TIMESTAMP_US value, or timestamp_us from JSON output, in the recovery commands below.

Recover with the CLI

Set RESTORE_TO_US to the timestamp you chose from the mutation history. Replace the example value below, then start recovery with the owning user’s profile:

RESTORE_TO_US=1792444364000000
dbx agent undo build-agent \
  --since-us "$RESTORE_TO_US" \
  --profile standalone-user

Alternatively, pass a TIMESTAMP_UTC value to --since. It accepts an RFC3339 timestamp that includes a timezone, such as 2026-10-12T14:30:00Z. Supply exactly one of --since or --since-us. The agent argument can be an alias in the profile or an agent ID.

The command returns a cursor, valid for 30 days. Replace CURSOR below with that value:

dbx agent undo-status --profile standalone-user -- CURSOR

CLI status is in_progress, complete, or failed. Check again while it is in_progress. A successful status lookup exits with code 0 for all three states, so scripts must inspect status to determine the job’s outcome. Use --output=json for structured output and read result.status.

After undo completes, listing mutations again can show a rollback entry with agent writes restored to followed by the restore timestamp. Earlier mutation entries remain in the history even when their writes were undone.

Recover with the API

Choose a timestamp from agents/mutations/list and set RESTORE_TO_US as shown above. Start recovery through agents/restore_writes with the agent ID and chosen timestamp:

curl https://api.dropboxapi.com/2/agent_filesystem/agents/restore_writes \
  --header "Authorization: Bearer $USER_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"agent\": {\".tag\": \"agent_id\", \"agent_id\": \"dbaid:agent\"},
    \"restore_to_timestamp_us\": $RESTORE_TO_US
  }"

Use the returned cursor to check agents/restore_writes/status with the same user’s token and app:

curl https://api.dropboxapi.com/2/agent_filesystem/agents/restore_writes/status \
  --header "Authorization: Bearer $USER_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"cursor": "CURSOR"}'

The response contains status as a tagged value. Continue polling while its .tag is restore_agent_writes_status_in_progress. Terminal values are restore_agent_writes_status_complete and restore_agent_writes_status_failed.

Recovery results

Recovery preserves later changes by other actors when handling conflicts. Completion does not guarantee that every selected revision was restored. Changes already restored remain in place if the job later fails.

The same user and app can continue checking a started job’s status after the agent is deleted.