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

# Mount

The Agent Filesystem CLI mounts a user's Dropbox or an agent workspace as a
local directory. A user mount lets a trusted process add and manage files as
the user. For an agent in a sandbox, VM, container, or CI job, create an agent
once, then mount its workspace for each runtime.

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

## Before you begin

You need:

* An app enabled for the Private Preview. Follow
  [Application Setup](/agentfs/docs/get-started/application-setup) first.
* The `dbx` CLI installed as described below.
* A Linux runtime with FUSE support.
* An empty directory for the mount.

## Download the CLI

[Download the dbx CLI for Linux x86-64](https://www.dropbox.com/scl/fi/k9bp104n2f7mev1kkod0w/dbx?rlkey=o2diyh63h93m0254063szcgx5\&raw=1).
The examples below use `dbx`. Make it executable and put it in a directory
on your `PATH`:

```bash
chmod +x dbx
export PATH="$PWD:$PATH"
```

## Configure credentials

Run setup commands from a trusted environment. Choose one of these user
flows, then use its `standalone-user` profile in the remaining examples.

### Existing Dropbox user

Sign in with your enabled app's key and follow the authorization instructions
printed by the CLI:

```bash
dbx login --app-key 'your-app-key' --profile standalone-user
```

The CLI stores credentials and agent alias mappings in named profiles.
Use a separate user profile for each user or environment that needs isolation.

### Managed user

Create an Agent Filesystem application through
[Application Setup](/agentfs/docs/get-started/application-setup#managed-users).
Sign in as the app, create a user alias, then save that user's token in a
separate user profile:

```bash
dbx login --app --app-key 'your-app-key' --profile provider
dbx user create app-user --name 'Example user' --profile provider
dbx login --user app-user \
  --app-profile provider \
  --profile standalone-user
```

The CLI reads the app secret from `DBX_APP_SECRET` or a terminal prompt for
each app-authenticated command. It saves the app key and aliases, but does
not save the secret. Managed-user tokens cannot be refreshed; run the
`dbx login --user` command again to replace an expired token while preserving
the profile's agent aliases.

To mint a user token for backend file API calls without saving it as a profile:

```bash
dbx user token app-user --profile provider
```

This prints only the token. `--scope` accepts comma-separated or repeated
scopes; by default it requests all supported managed-user scopes, including
agent management and recovery. Each requested scope must be enabled for your
app. `dbx login --user` also requires `account_info.read` to identify the user.

If your backend issues the token separately, import its JSON output without
app credentials:

```bash
dbx login --token --profile standalone-user < user-token.json
```

Use the complete output of `dbx user token --output=json` so the profile has
the expiry and scopes needed for a user mount. See
[Authentication](/agentfs/docs/concepts/authentication#sign-in-with-a-token-issued-elsewhere)
for the handoff commands. Token imports start with fresh agent aliases; keep
agent IDs when replacing an imported token.

## Mount as the user

To work with files as the signed-in user, mount the saved profile's account
root:

```bash
mkdir -p /workspace/user-files
dbx mount start --user /workspace/user-files --profile standalone-user
```

This works with regular OAuth profiles and managed-user profiles. The profile
must have a known token expiry, `files.metadata.read`, and `files.content.read`.
Without `files.content.write`, the mount is read-only. `DBX_TOKEN` and raw
token imports cannot be used for user mounts. `--scope` applies only to agent
mounts; user mounts use the saved token's scopes.

OAuth user mounts refresh credentials automatically. Managed-user mounts flush
and unmount before the token expires. Sign in with a new managed-user token
and restart the mount to continue.

Files written through this mount are attributed to the user. Agents with
workspace access to those files see the same content, and undoing an agent's
writes preserves the user's later work. For example, create the folder used
in the agent examples below, then stop the user mount:

```bash
mkdir -p /workspace/user-files/Projects/build-output
dbx mount stop /workspace/user-files
```

Paths are relative to the account root. Include the member folder name when
accessing content inside that folder.
See [CLI paths](/agentfs/docs/concepts/workspaces#cli-paths).

## Create an agent

Every agent acts for the user identified by its profile.

Create an agent alias:

```bash
dbx agent create build-agent --profile standalone-user
```

## Grant workspace access

The target folder must exist before you grant access. Create it using a
[user mount](/agentfs/docs/concepts/mount#mount-as-the-user) or
[`files/create_folder_v2`](/dropbox-api/api-reference/user-endpoints/files/create-folder-v-2)
with the user token.

Grant read and write access to the folder:

```bash
dbx agent workspace add \
  build-agent \
  /Projects/build-output \
  read_write \
  --profile standalone-user
```

Roles are `read_write`, `read`, or `none`. Use `read` for content the agent
must not change and `none` to deny access. Workspace commands accept a path
or an `id:` value, and `/` selects the account root. Paths are relative to the
account root. Include the member folder name when accessing content inside
that folder. See [Workspaces](/agentfs/docs/concepts/workspaces#cli-paths) for examples.
The agent cannot access content outside its workspace or exceed the user's
permissions.

To set initial rules during agent creation, pass repeatable
`--add PATH=ROLE` flags to `dbx agent create`, such as
`--add /Projects/build-output=read_write`.

Keep the user profile in the trusted process that launches the runtime. Do not
copy it into the agent's working directory.

## Mount the workspace

Run the mount command when your product starts the runtime:

```bash
mkdir -p /workspace/agent-files
dbx mount start \
  build-agent \
  /workspace/agent-files \
  --profile standalone-user
```

The CLI mints a short-lived agent token and starts the mount in the background.
It automatically mints replacement agent tokens with the same agent and
scopes, using the original user profile. OAuth user credentials can refresh
automatically. For a managed user, replace the user token in that same profile
before it expires with `dbx login --user` or import replacement token JSON
with `dbx login --token`. Token imports clear local agent aliases; an existing
mount continues to identify its agent by ID.

If token renewal fails, the CLI attempts to flush pending writes and unmount
before the current agent token expires. To check or stop a mount:

```bash
dbx mount status
dbx mount stop /workspace/agent-files
```

Use `--foreground` to serve the mount in the current process until Ctrl-C or
SIGTERM. For agent mounts, `--scope` accepts comma-separated or repeated file
scopes and optional `account_info.read` for account-root discovery. By default,
the CLI uses the supported scopes saved in the user profile. If you use a raw
token import or `DBX_TOKEN`, specify `--scope` explicitly. A mount without
`files.content.write` is read-only.

The mounted agent will be able to use normal file operations:

```bash
find /workspace/agent-files -maxdepth 3 -type f
printf 'Build completed\n' > /workspace/agent-files/Projects/build-output/result.txt
```

Writes to a read-only path will fail. Content outside the workspace will not be
visible through the mount.

See [Authentication](/agentfs/docs/concepts/authentication) for credential
storage and [Recovery](/agentfs/docs/concepts/recovery) for undoing agent writes.

For automation, use `--output=json`. Successful command data is in `result`;
failures include `error.code` and, when supplied by Dropbox,
`error.details.error_summary`.