> This page is for Agent Filesystem.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dropboxapi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server.

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

> **Warning**
>
> Agent Filesystem is in Private Preview and is subject to change. Contact
> your Dropbox representative to request access.

## 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](/agentfs/docs/get-started/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`](/agentfs/api-reference/agent-filesystem/agents-mutations-list)
API endpoint:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](/agentfs/api-reference/agent-filesystem/agents-mutations-list)
and set `RESTORE_TO_US` as shown above. Start recovery through
[`agents/restore_writes`](/agentfs/api-reference/agent-filesystem/agents-restore-writes)
with the agent ID and chosen timestamp:

```bash
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`](/agentfs/api-reference/agent-filesystem/agents-restore-writes-status)
with the same user's token and app:

```bash
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.