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

# Quickstart

This example generates a client from the OpenAPI document, creates an agent
for a user, and writes a file with the agent's runtime token. Use an existing
Dropbox user's token or a token minted for a managed user.

Choose TypeScript or Python in the code switcher.

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

## Before you begin

You need:

* An app enabled for the Agent Filesystem Private Preview. Follow
  [Application Setup](/agentfs/docs/get-started/application-setup) to create
  an Agent Filesystem application in the Developer Console.
* A user access token with the required file and Agent Filesystem scopes.
* Java 11 or later for OpenAPI Generator.
* Node.js 18 or later for TypeScript, or Python 3.10 or later for Python.

Download the [Agent Filesystem OpenAPI document](/openapi/api-reference-3.yaml)
and save it as `agentfs-openapi.yaml` in your project.

## Generate the client

These commands use OpenAPI Generator 7.26.0. Pin the generator version in your
project so regenerated clients keep a predictable interface.

### TypeScript

```bash
npm install --save-dev \
  @openapitools/openapi-generator-cli \
  @types/node \
  tsx \
  typescript
npx openapi-generator-cli version-manager set 7.26.0

npx openapi-generator-cli generate \
  -i agentfs-openapi.yaml \
  -g typescript-fetch \
  -o generated/agentfs \
  --additional-properties=npmName=agentfs-client

npm install ./generated/agentfs dropbox
```

### Python

```bash
python3 -m pip install openapi-generator-cli==7.26.0

openapi-generator-cli generate \
  -i agentfs-openapi.yaml \
  -g python \
  -o generated/agentfs \
  --additional-properties=packageName=agentfs_client,projectName=agentfs-client,poetry1=true

python3 -m pip install ./generated/agentfs dropbox
```

## Set the credentials

To test with your own Dropbox account, open your enabled app in
[My apps](https://www.dropbox.com/developers/apps), find the **OAuth 2** section
of its settings, and click **Generate**. This creates a user access token for
your account. To get a token for another user, follow the
[OAuth guide](/dropbox-api/docs/oauth) to connect them through your app.

For a managed user, follow the
[managed user flow](/agentfs/docs/concepts/authentication#managed-user-flow)
to create the user and mint a token, then use that token below.

Set the resulting token in a trusted server-side environment:

```bash
export DROPBOX_USER_ACCESS_TOKEN='your-user-access-token'
```

Keep the user token in your trusted backend. Give the agent runtime only its
short-lived agent token.

## Run the example

#### TypeScript

```typescript
import {
  AgentFilesystemApi,
  Configuration,
} from "agentfs-client";
import { Dropbox } from "dropbox";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

async function main(): Promise<void> {
  const userAccessToken = required("DROPBOX_USER_ACCESS_TOKEN");
  const sampleId = Date.now().toString(36);

  const userConfiguration = new Configuration({
    accessToken: userAccessToken,
  });
  const workspacePath = `/agentfs-sample-${sampleId}`;
  const userFiles = new Dropbox({ accessToken: userAccessToken });
  await userFiles.filesCreateFolderV2({
    path: workspacePath,
    autorename: false,
  });

  const agents = new AgentFilesystemApi(userConfiguration);
  const created = await agents.agentFilesystemAgentsCreate({
    agentFilesystemCreateAgentsArg: {
      entries: [{
        workspace: [{
          path: workspacePath,
          role: { tag: "read_write" },
        }],
      }],
    },
  });
  const agentId = created.agents[0].agentId;

  const runtime = await new AgentFilesystemApi(
    userConfiguration,
  ).agentFilesystemAgentsAccessTokenMint({
    agentFilesystemMintAgentAccessTokenArg: {
      agent: { tag: "agent_id", agentId },
      scope: "files.metadata.read files.content.write",
    },
  });

  const runtimeFiles = new Dropbox({ accessToken: runtime.accessToken });
  const uploadPath = `${workspacePath}/agent-result-${sampleId}.txt`;
  await runtimeFiles.filesUpload({
    path: uploadPath,
    mode: { ".tag": "overwrite" },
    autorename: false,
    contents: Buffer.from("Created by an Agent Filesystem runtime.\n"),
  });

  console.log(`Agent ID: ${agentId}`);
  console.log(`Uploaded: ${uploadPath}`);
}

main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});
```

Save the example as `agentfs-example.ts`, then run it from the trusted
environment where you set the variables.

```bash
npx tsx agentfs-example.ts
```

#### Python

```python
import os
import time

import agentfs_client
import dropbox


def required(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"Missing {name}")
    return value


user_access_token = required("DROPBOX_USER_ACCESS_TOKEN")
sample_id = str(time.time_ns())[-8:]

user_configuration = agentfs_client.Configuration(
    access_token=user_access_token
)
workspace_path = f"/agentfs-sample-{sample_id}"
user_files = dropbox.Dropbox(oauth2_access_token=user_access_token)
user_files.files_create_folder_v2(workspace_path, autorename=False)

with agentfs_client.ApiClient(user_configuration) as user_client:
    agents = agentfs_client.AgentFilesystemApi(user_client)
    created = agents.agent_filesystem_agents_create(
        agentfs_client.AgentFilesystemCreateAgentsArg.from_dict(
            {
                "entries": [{
                    "workspace": [{
                        "path": workspace_path,
                        "role": {".tag": "read_write"},
                    }],
                }]
            }
        )
    )
    runtime = agentfs_client.AgentFilesystemApi(
        user_client
    ).agent_filesystem_agents_access_token_mint(
        agentfs_client.AgentFilesystemMintAgentAccessTokenArg.from_dict(
            {
                "agent": {
                    ".tag": "agent_id",
                    "agent_id": created.agents[0].agent_id,
                },
                "scope": "files.metadata.read files.content.write",
            }
        )
    )

runtime_files = dropbox.Dropbox(oauth2_access_token=runtime.access_token)
upload_path = f"{workspace_path}/agent-result-{sample_id}.txt"
runtime_files.files_upload(
    b"Created by an Agent Filesystem runtime.\n",
    upload_path,
    mode=dropbox.files.WriteMode.overwrite,
    autorename=False,
)

print(f"Agent ID: {created.agents[0].agent_id}")
print(f"Uploaded: {upload_path}")
```

Save the example as `agentfs_example.py`, then run it from the trusted
environment where you set the variables.

```bash
python3 agentfs_example.py
```

Store the returned agent ID. Your backend uses it to mint later tokens and
manage the same agent.

## Which credential goes where

| Credential          | Used by           | Purpose                                                 |
| ------------------- | ----------------- | ------------------------------------------------------- |
| User token          | Trusted backend   | Create the folder and agent, then mint a runtime token. |
| Agent runtime token | Agent environment | Upload the file inside the workspace.                   |

Only the runtime token enters the agent environment.

## Managed users and tenants

The same agent and file operations work with a managed user's token. Tenants
are **Coming soon** and will add a separate administration and credential
boundary.

See [Authentication](/agentfs/docs/concepts/authentication) for
token storage, caching, and revocation guidance.