Files

Files

A drive of folders and files for your agents and you, with every version of each.

Files are built in, like the Vault: a drive of folders and files kept in Personal Agent Proxy itself, rather than an outside service you connect. It is where you hand your agents a file and where they put what they make for you: notes, a report, a spreadsheet as CSV. Nothing written to a file is lost: every write is the file's next version, and the ones before stay, each with who made it, so whatever an agent wrote over can be given back.

You have a drive of your own in every organization, as you have a vault: nobody else in the organization sees it, and it can't be shared (Organizations). Your own agents reach it; a shared agent has none.

For files that are more than yours, a team's documents or a project's working files, make a drive beside your own: Add connection, then Files, and give it a name, which is what it is called here and to agents, who go by it for what to put in it. A drive you made is shared as any connection is, with everyone in the organization or with members by name, on its Sharing tab: the people it is shared with, and their agents, read it and add to it as you do, and only you rename it, share it on or delete it. Deleting it deletes its files, for good.

Choose what agents can do

Files have four actions: Read files, which lists folders, opens files and shows their earlier versions; Add files, which adds files and folders, never over one that is there; Edit files, which writes over a file, renames it, moves it and gives an earlier version back; and Move to trash, which moves files and folders to the trash and takes them out again. Your own agents get all four by default, since nothing done to a drive is lost. Change any on an agent's page, or for every agent there as the default.

Put files in, and see what your agents made

Open Connections and permissions in the sidebar, then My files, or a drive by its name. Upload with the button or by dropping files on the list; make folders; open a folder by its row. The search finds files and folders by name, in the folder you are in and everything below it, and says where each one is. A row's menu renames a file or a folder, moves it into another folder of the drive, or puts it in the trash. A file opens with what it is, a picture as it is, and its versions, newest first: each with when it was made and by whom, you or an agent, with the task the agent made it for. Download saves a version, Restore gives it back as the file's next version, and Upload new version replaces what the file holds, keeping what it held.

Empty the trash, or don't

Move to trash takes a file, or a folder with everything in it, out of the drive without deleting it; Trash lists what is there, and takes it out again. What stays in the trash is deleted for good after 30 days.

Files in a chat

On the Chat page, attach files to what you say, in the chat or in a thread, with the paperclip, by pasting, as a screenshot, or by dropping them anywhere on the window. A file goes into the message where you are typing, as a word does, so you can write around it, and the agent reads it named in that place. It is uploaded the moment you put it there, and waits in the message with what you have typed, in the chat's box on any device, until you send the message or take it out again, by deleting it or by the cross that shows under the pointer. It is kept in your own drive, in a folder of the agent's under Chats, so it is there afterwards as any file of yours is; taking it out of a message leaves it there. The thread goes on meaning the file as it was when you attached it, whatever it holds later.

The agent reads a text file, a PDF, a Word document or a spreadsheet with your message, the first of it where it is long, and reads the rest when it needs it. A picture, a screenshot or a photograph, it sees as you do, where the model it answers with sees pictures: every Claude model does. It is given the pictures of your last two messages, each made small enough to send, so one from further back has to be attached again to be looked at again. Attaching a file lets the agent working in that thread read that version of it, whatever it may otherwise do in your drive.

The agent can show you a picture too, such as a chart it made in a sandbox or a screenshot already in a drive: it puts the picture in a drive and shows it in its answer, where its words put it, and clicking it opens the file in its drive. Like an attachment, the answer keeps the version it showed, whatever the file holds later. It only shows a file from a drive it may read; any other file it shows appears as a chip. A picture from anywhere else on the web appears as a link and is never loaded by itself, so an answer can't make your browser send anything to another site.

Agents and files

An agent that may read a drive lists its folders, searches it by name, and reads a file as text: text as it is, a spreadsheet's tabs as CSV, a PDF's or a Word document's text, a long one a stretch at a time. It adds files and writes them as text, and puts any other file in the drive as a blob, from an email's attachment, another drive or its own shell (below).

To write over a file, an agent has to name the version it read. Where the file changed since, by you or another agent, the write is refused and the agent reads the file again, so one never writes over what it hasn't seen. Every write, rename, move and trip to the trash is in the activity log under the task it was made for, and the file's own history says which agent made each version.

An agent points you to a file it made by its link, which opens the file in your drive.

Moving files between connections

A file that isn't text, or is too large to send as a tool's words, a PDF, a picture, a spreadsheet or an archive, moves through Personal Agent Proxy as a blob: its bytes, kept for a day, which only the agent that made it can use. One tool hands a file over as a blob, and another takes the blob where it goes, each checked against what the agent may do with its own connection and in the activity log under it:

  • files_blob makes a blob of a file in a drive, what it holds now or an earlier version, as reading it does. Google Drive's makes one of a file there, a Doc, Sheet or Slides file as Drive exports it.
  • attachments_blob makes a blob of an email's attachment, of any kind, in Gmail or any mailbox.
  • files_upload puts a blob in a drive: a new file, called what the blob is unless the agent names it otherwise, in the folder given, or the next version of a file whose version the agent read, keeping the one before. It needs Add files for a new file and Edit files to write over one, and the file is in the drive's history as the agent's, for the task it was put there for.
  • An email attaches blobs: a new draft, an edit of one, a reply, or an email sent at once names them in attach, in Gmail or any mailbox, and they go out under their own names, 25 MB together at most.

So an attachment goes into a drive in two calls, attachments_blob and then files_upload, and a file from Google Drive into Files, or the other way, the same way with files_blob. An attachment is forwarded the same way, made a blob and attached to the new email, and so is a file of a drive sent by email.

A file from wherever the agent runs, with a shell and curl and nothing of Personal Agent Proxy's installed, becomes a blob through a URL: pap.upload() in a script answers with one, and curl -T report.pdf '<url>?name=report.pdf' sends the file to it, answered with the blob's id. pap.download(blob) answers with a URL to fetch a blob from. Each URL is the only key it needs, so it needs no sign-in, and works for an hour. Nothing is in a drive until files_upload puts it there, and a blob nobody used is deleted after its day.

Files in a sandbox

An agent that also runs commands in a sandbox moves files between a drive and the sandbox as they are, a picture, a spreadsheet or an archive as much as text, with pap files, which a command with pap turned on can run:

  • pap files ls <connection> [path] lists a folder by its path from the drive's top, such as Reports/2026.
  • pap files pull <connection> <path> [to] brings a file into the sandbox, under its own name or to the path given. --id with --version pulls a file by its id at one version, which is how a file you attached in a chat is brought in.
  • pap files push <file> sends a pulled file back as its next version, and pap files push <file> <connection> <path> sends any file to a path, making the folders on the way.

A push is a blob put in the drive, which pap makes for the agent. It reads the file's size and SHA-256 from the sandbox's disk and asks about the push before any of the file is sent: whether the agent may make it, where it goes, the version it names and the file's size, so a push that would be refused sends nothing. Then it sends the file to a blob's URL as it reads it, checks that what arrived is what it read, and puts the blob at the path, making the folders on the way. pap upload <file> and pap download <blob> move a blob alone, for the other tools that take or make one.

The rule of a write holds here too: a push over a file is taken where the file still holds the version that was pulled, and refused where it changed since, unless it is pushed with --force; the version before is kept either way. A pull is a read, a push to a new path an added file, and a push over a file an edit, each checked against what the agent may do with the drive and in the activity log as from a sandbox, a push as its files_upload.

pap files works on a Google connection's Drive too, with paths from My Drive, Shared drives and Shared with me, and Docs, Sheets and Slides files pulled as an export (Google).

Where the bytes are

A drive's folders, names and versions are in the database; the bytes of each version are in the blob store the server is set up with: a directory on the server (FILES_DIR), for one server with a volume that is kept, or a bucket that speaks S3's protocol (FILES_S3_BUCKET), Amazon's, Cloudflare R2's or MinIO's, for servers that share no disk. A file is never served as a page of Personal Agent Proxy's: it downloads, except a picture, which shows. The largest file taken is 100 MB unless FILES_MAX_MB says otherwise, up to 2047 MB.