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.

Before you begin

You need:

• An app enabled for the Private Preview. Follow 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. The examples below use dbx. Make it executable and put it in a directory on your PATH:

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:

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. Sign in as the app, create a user alias, then save that user’s token in a separate user profile:

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:

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:

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

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:

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.

Create an agent

Every agent acts for the user identified by its profile.

Create an agent alias:

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 or files/create_folder_v2 with the user token.

Grant read and write access to the folder:

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

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:

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:

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 for credential storage and 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.