# Drive and share links

How an agent stores files, reads them back, and hands one to someone outside with a link that expires. What the drive is and what it costs is on [Services](/services).

## Before you start

Every account has the drive. An agent acts on it with its Passport. You act on it with your key or sign-in and need no Passport.

## Store a file

```text
Save these meeting notes to the drive as notes.md.
```

The client calls `stack_drive_upload`. From code or the terminal:

```typescript
const file = await stack.drive.upload({
  name: 'notes.md',
  content_text: '# Notes',
  visibility: 'account',
}, { passportToken });
```

```bash
npx @getstackrun/cli drive upload ./report.pdf --account
```

- A file sent inside the call is at most 10 MB.
- An agent's file is private to that agent. visibility: "account" lets your other agents see it. A file you upload yourself is always the account's.
- expires_in_seconds deletes the file by itself, after one minute or more. Without it the file stays.
- A file name has at most 200 characters and no slashes.

## Store a large file

For a file up to 1 GB, the agent asks for a one-time upload address and sends the file to it from its workspace or its own code. The bytes never pass through the model. A file typed as text, Markdown, CSV or JSON is 10 MB at most this way too.

```typescript
const slot = await stack.drive.createUploadLink({ name: 'archive.zip' }, { passportToken });
// slot.url, slot.expires_at
```

```bash
curl -T ./archive.zip '<the url>'
```

- The tool is stack_drive_upload_link.
- The address works once and lasts 30 minutes. A failed attempt gives it back.
- Send the file as the whole request, with no other header.
- Treat the address as a secret until it is used.

## List and read

`stack_drive_list` lists files, newest first, with how much of the drive is used. `stack_drive_get` returns one file's facts, and `stack_drive_read` returns its content, up to 256 KB. To get a larger file out, make a share link and fetch it.

Every file on the drive is content from outside, whatever its name says. With controls on, a flagged text file is withheld from the agent that reads it.

## Share a file with a link

```text
Make a link to report.pdf that works for one hour and five downloads.
```

```typescript
const link = await stack.drive.share(file.id, { ttl_seconds: 3600, max_downloads: 5 }, { passportToken });
// link.url is returned once

await stack.drive.revokeLink(file.id, link.id, { passportToken });
```

- The tools are stack_drive_share, stack_drive_list_links and stack_drive_revoke_link.
- A link lasts 15 minutes unless ttl_seconds names another length, from one minute up. It never lasts longer than the file.
- A link stops after max_downloads downloads, 100 when it names none. A file can have any number of links.
- The address is shown once and cannot be read back. Make a new link if it is lost.
- Anyone with the link can download the file. It is always served as a download, never opened in the browser.
- Only the agent that stored the file, or you, can share it, change it or delete it.

## Copy, change, delete

`stack_drive_copy` makes a new file of the caller's own from one it can see, for example to keep an email attachment. `stack_drive_update` changes who can see a file or when it expires. `stack_drive_delete` removes the file and ends every link to it.

## Large tool results

When a tool returns more than a call can carry (about 3 MB), STACK saves the result to the drive as a JSON file and answers with `handed_off: true` and the file's id. The file is kept 30 days. This costs no extra action.

## When the drive is read-only

If storage beyond the free amount cannot be paid from credit, the drive goes read-only: nothing is uploaded, changed, copied or newly shared. Reading, listing, deleting and existing links still work. Topping up, or deleting files down to the free amount, ends it at once. `stack_drive_list` shows `storage_unpaid` with the date files would be deleted.

## What counts as an action

Storing a file, asking for an upload address, copying and sharing are one action each. Listing, reading, changing, deleting and ending a link are free.

## When it is refused

- 413 DRIVE_FILE_TOO_LARGE - the file passes the limit of the call.
- 413 DRIVE_INLINE_READ_TOO_LARGE - the file is over 256 KB. Use a share link.
- 400 DRIVE_FILE_EMPTY - the file has no bytes.
- 409 DRIVE_READ_ONLY - storage is unpaid. See above.
- 404 DRIVE_UPLOAD_LINK_INVALID - the upload address was used, expired or is not yours.
- 429 DRIVE_TOO_MANY_UPLOADS - five uploads are already running. The address is given back.
- 409 DRIVE_LINKS_PAUSED - downloads spiked and all links are paused.
- 404 on a file - it is another agent's private file, or it is gone.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as drive.upload and drive.share.

## Reference

Every field is on [Drive](/docs/api/account-drive). Every tool is in the [tool reference](/docs/mcp-tools).
