Skip to navigation

Quickstart

Create an agent workspace, write a persistent file, and try agent-specific undo.

View as Markdown

Before you begin

You need Agent Filesystem access, Linux x86-64 with FUSE, and a writable /workspace directory. Run setup in a trusted environment and keep the user profile outside the agent’s working directory.

1

Create your app

  1. Open Developer Console Credentials, click Create credential, and select Agent Filesystem.
  2. Enter a unique application name, click Create application, and copy the App key and App secret.

Complete email verification or developer onboarding if prompted.

Creating this credential creates a Dropbox app for your integration. Managed users are separate API-only users you create later; they do not need another Dropbox signup.

Credential security

Store credentials in your backend secret store; keep the app secret out of browser and agent code.

2

Install the CLI and connect a user

curl -fsSL -o dbx https://github.com/dropbox/agent-filesystem-samples/releases/download/dbx-cli-latest/dbx-linux-amd64
chmod +x dbx
export PATH="$PWD:$PATH"
dbx --version

Choose one sign-in path. Both use the standalone-user profile below.

Replace your-app-key and follow the CLI’s authorization instructions.

dbx login --app-key 'your-app-key' --profile standalone-user
3

Mount your Dropbox

Mount the account you signed in as in Step 2. You’ll use it to create the agent’s folder and to check the agent’s work. A new managed user’s Dropbox starts empty.

mkdir -p /workspace/dropbox
dbx mount start --user /workspace/dropbox --profile standalone-user
ls /workspace/dropbox
4

Create an agent with a scoped workspace

An agent can use only the folders in its workspace, and each folder must already exist. --add takes a path in your Dropbox, not on this machine.

mkdir /workspace/dropbox/AgentFSQuickstart
dbx agent create quickstart-agent --add /AgentFSQuickstart=read_write --profile standalone-user

On a team account, put your member folder before AgentFSQuickstart in every path from here on, and quote paths with spaces: for example, mkdir '/workspace/dropbox/Jane Doe/AgentFSQuickstart' and --add '/Jane Doe/AgentFSQuickstart=read_write'. See workspace paths.

5

Write and verify a persistent file as the agent

Mount the agent’s workspace in a second local directory. Both mounts show the same Dropbox folder, but the agent sees only its workspace. dbx mount syncs files with Dropbox automatically.

dbx mount uploads it dbx mount downloads it Agent writes hello.txt in/workspace/agent Your Dropbox You read it in /workspace/dropbox
mkdir -p /workspace/agent
dbx mount start quickstart-agent /workspace/agent --profile standalone-user
ls /workspace/agent
# AgentFSQuickstart
echo 'Hello, AgentFS' > /workspace/agent/AgentFSQuickstart/hello.txt

After the file syncs, read it through the user mount:

cat /workspace/dropbox/AgentFSQuickstart/hello.txt
# Hello, AgentFS
6

Inspect and undo the agent's write (optional)

Stop the agent’s mount so no writes are in progress, then find its write in the mutation history:

dbx mount stop /workspace/agent
dbx agent mutations quickstart-agent --profile standalone-user

Copy the TIMESTAMP_US for hello.txt and undo from there:

dbx agent undo quickstart-agent --since-us 'paste-TIMESTAMP_US-here' --wait --profile standalone-user
ls /workspace/dropbox/AgentFSQuickstart
# (empty: hello.txt is gone, and your folder stays)

See Recovery for what undo can and can’t restore.

When you’re done, stop your mount. If you skipped Step 6, stop the agent’s mount first with dbx mount stop /workspace/agent.

dbx mount stop /workspace/dropbox

For production token handling, see Authentication. For mount lifecycle and runtime isolation, see Mount.