STACK
MENU
DOCS / THE ACCOUNT / DRIVE AND SHARE LINKS

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.

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

prompt
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

prompt
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. Every tool is in the tool reference.

Drive and share links | Docs