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

# Workspaces

An agent workspace is a set of access rules. It is not a separate file
container or a copy of the user's content.

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

## Effective access

An agent can use a file only when every access layer allows the operation:

1. The app has the required permission.
2. The user token and agent token include the required OAuth scope.
3. The user has access to the file.
4. The agent's workspace role allows the operation.

User permissions set the maximum access. Token scopes and workspace rules can
reduce that access. They cannot grant access that the user lacks.

## Workspace roles

| Role         | Effect                                                                                         |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `none`       | Deny access to the selected item.                                                              |
| `read`       | Allow supported metadata and content reads.                                                    |
| `read_write` | Allow reads and supported content changes.                                                     |
| `remove`     | Delete an explicit rule during an edit. This role is not returned when you list the workspace. |

A folder rule also applies to its descendants. A more specific rule overrides
a broader rule. Access is denied when no rule matches.

Workspace edits leave omitted rules unchanged. Updated rules apply to active
and new agent tokens.

In API requests, use `""` to edit the root rule; `"/"` is not accepted as the
root path. `dbx agent workspace` accepts `/` for the root and translates it to
`""`. The root rule is identified by an empty `path` in workspace responses.
If a file or folder was deleted or is no longer visible, its response may omit
`path`; remove that rule with its `file_id`.

## CLI paths

For team users with a team space, CLI workspace paths and mounted paths are
relative to the account root. Include the member folder name when referring
to content in that folder. For example, `/Projects/build-output` in a member's
Dropbox folder may be `/Jane Doe/Projects/build-output` from the account root.
The mount uses that same path beneath its mount point.

For personal accounts, paths are relative to your Dropbox folder and do not
include a member folder name. Use `/Projects/build-output` directly.

You can also use a file or folder's `id:` value to grant workspace access
without depending on its current path. Direct API requests use the namespace
selected by `Dropbox-API-Path-Root`; without that header, file paths are
relative to the user's home namespace.

## User permissions

Control user access with the standard Dropbox sharing APIs. For example, use
[`sharing/share_folder`](/dropbox-api/api-reference/user-endpoints/sharing/share-folder)
to create a shared folder and
[`sharing/add_folder_member`](/dropbox-api/api-reference/user-endpoints/sharing/add-folder-member)
to add members.

Sharing changes the files that the user can access. It does not add those files
to an agent workspace. Add or update a workspace rule separately when an agent
also needs access.

See [Sharing](/dropbox-api/docs/sharing) for the full sharing model and
[File Operations](/agentfs/docs/concepts/file-operations) for supported file
requests and scopes.