Skip to content

workspace files

Dr K edited this page Nov 14, 2026 · 4 revisions

Workspace files

A workspace keeps files in four sections: Downloads, Screenshots, Recordings and Files. This area covers where each is stored, how a file gets in, how it is listed, read and opened by signed link, how a recording is made and filed, and how a name from outside is made safe.

Use cases

  • An agent takes a screenshot and hands the person its url, which opens without a token.
  • An agent downloads an export in the browser, keeps it with keep_file, and attaches it to another page with upload_file(file=...) without the bytes passing through the model.
  • An operator records a browser with open_session(record=true) and watches the video afterwards.
  • An operator clears a workspace's screenshots, or deletes one kept file, in the admin UI.

Neighbours

FILE-1. The workspace record and its expiry are in workspaces-and-sessions.md. A signed link's signature, expiry and refusal are in auth-and-roles.md (AUTH-23 to AUTH-29), and so is the Admin door that guards the admin routes below. The tool and resource surfaces, the mirror tools and show are in surfaces.md. The scrub is in secrets-and-scope.md. record as an open_session option is in session-settings.md. How the Files tab draws is in admin-ui.md; this file holds the routes behind it.

The four sections

FILE-2. A workspace's files are in four sections that are never merged into one list. A file's address names its section, so a name only has to be unique inside its section.

Section Belongs to Where the bytes are Survives the browser
Downloads the browser the Grid's per-session store no
Screenshots the workspace <data>/workspaces/<name>/screenshots/ yes
Recordings the workspace <data>/workspaces/<name>/recordings/ yes
Files the workspace <data>/workspaces/<name>/files/ yes

FILE-3. <data> is data.dir. When data.dir is unset, Screenshots, Recordings and Files are off, and listing, reading and keeping them is refused with keeping files is not enabled on this server: it was started with no DATA_DIR, so there is nowhere to keep them. Downloads still work.

FILE-4. Files holds what a caller put there on purpose: a print, a kept screenshot, a kept recording, a kept download. Screenshots and Recordings hold what the server made until it is kept or cleared.

FILE-5. No folder has an expiry, a size cap or a file-count cap. A file leaves a folder only by Keep (a move out of Screenshots or Recordings), a clear, or a delete (FILE-42 to FILE-44). A workspace's record expires after workspace.ttl; its folders do not.

FILE-6. Downloads belong to the Grid. The Grid offers list, read one and delete all, so the server offers those and no per-file delete. A download lives until the browser ends, the Grid reaps it, or Downloads is cleared.

FILE-7. A Grid scratch entry is never listed or served as a download: a name ending .crdownload or .part, or starting with a dot.

Names

FILE-8. The reserved names inside Files are screenshots, recordings and downloads. A file arriving in Files under one lands as screenshots (1), recordings (1) or downloads (1).

FILE-9. A file the server makes, and a kept screenshot or recording, never overwrite a name. The next free name is name (1).ext, then name (2).ext, and so on. A name with no extension becomes name (1).

FILE-10. A file name in a folder (names.valid_file_name) is 1 to 255 characters, holds no /, no \, and no control character (\x00 to \x1f), does not start with a dot, and is not blank. It is not trimmed: " a.pdf " and a.pdf are two files. A name that fails is a 400 naming the rule.

FILE-11. A listing skips a file whose name starts with a dot (a staged copy, the notes folder), a name that fails FILE-10 (logged), a link, and anything that is not a regular file. A path is refused when it does not resolve to itself under the data directory, so a link left at <workspace>/files is never followed.

FILE-12. A name that comes from a caller for a file the server writes is narrowed by safe_name. It folds \ to /, keeps the last segment, strips surrounding whitespace and leading dots, and becomes upload when nothing is left. A name with no extension gets one.

FILE-13. For bytes the server made, the extension is forced too: the narrowed name keeps its text and gets .png, .pdf or .html appended when its suffix is not that type, case-insensitively. chart.pdf for a screenshot is chart.pdf.png, because the served type comes from the name (FILE-27).

FILE-14. safe_name takes its extension, when the name has none, from mime_type. The server's own table wins (JSON, XML, YAML, NDJSON, Markdown, CSV, TSV, plain text and HTML); otherwise the standard library's guess. A text upload with neither gets .txt.

Getting a file in

FILE-15. A browser download lands in the Grid's store for that browser. Nothing on this server copies it until keep_file does.

FILE-16. screenshot saves its PNG to Screenshots by default (save=true), under screenshot.png or filename, narrowed by FILE-13. A clash lands as screenshot (1).png. The result's file is the entry (FILE-24) and the name used is file.name.

FILE-17. screenshot(save=false) stores nothing. When saving fails, the image still comes back and the result carries file_error in place of file. file_error is the refusal's own text for a ValueError, and otherwise the capture could not be kept (<ExceptionType>), never a path.

FILE-18. print(format="pdf"|"html") writes straight to Files, under page.pdf or page.html or filename, narrowed by FILE-13. A PDF is the browser's W3C print, with landscape and background (off by default). HTML is the page source as the browser holds it now. The result has file, format and bytes. Any other format is a 400.

FILE-19. A print that cannot be kept fails the call with the print could not be kept (<ExceptionType>), not a path. With no DATA_DIR it fails with the FILE-3 message.

FILE-20. upload_file takes exactly one of text, content (base64) or file (a file's address, FILE-25). An empty string counts as not given, and zero or more than one is a 400. A content that is not base64 is a 400 that points at the multipart form of the HTTP route. The page sees the name from safe_name(filename or the file's own name, mime_type), and reads its type from the extension.

FILE-21. upload_file writes the bytes to a temporary directory, hands the path to the file input, and removes the directory afterwards. Selenium ships the file to the Grid node, whose browser cannot see this filesystem. A directory that cannot be made is a server error naming /tmp and TMPDIR. A path on this server is never accepted.

FILE-22. See SURF-35 for the caps on an HTTP request body. An MCP call has no cap of its own.

FILE-23. upload_file(file=...) reads from the workspace that owns the call. Inside a flow run it reads from the workspace running the flow, which a flow in the shared library relies on, and only a flow run can name another library for file, through the capability row's library_arg. An address outside Downloads is refused with the FILE-3 message when data.dir is unset.

Describing a file

FILE-24. Every surface describes a file the same way: name, uri, size in bytes, created in epoch milliseconds, content_type, image, url, and for a screenshot, a recording or a download, keep_with (the exact keep_file("<uri>") call, the uri JSON-quoted). image is true for PNG, JPEG, GIF, WebP, AVIF and SVG.

FILE-25. An address is one of:

Section Address
Files workspace://files/<name>
Screenshots workspace://files/screenshots/<name>
Recordings workspace://files/recordings/<name>
Downloads session://downloads/<name>

A name is percent-encoded in an address. workspace://files/downloads... and session://files/... are refused with a message naming the current spelling.

FILE-26. url is signed (FILE-36) and absolute when public_base_url is set, otherwise relative to the mount. With auth off it is the plain path.

FILE-27. content_type is guessed from the name (mimetypes), with .webp and .avif added, and application/octet-stream when it has no guess.

Listing and reading

FILE-28. The resources are workspace://files (Files and the two folders with their counts, not expanded), workspace://files/screenshots, workspace://files/recordings and session://downloads. Each listing is newest first and carries workspace, folder, uri, count and files.

FILE-29. Reading workspace://files/<name>, .../screenshots/<name> or session://downloads/<name> returns the bytes with the file's media type. Reading a Files entry whose type starts video/ returns the entry as JSON, and so does .../recordings/<name>: a model cannot watch a video, and a resource would carry it as base64. The url in the entry plays it.

FILE-30. The same operations are HTTP routes on the caller's workspace (named by header or ?workspace=): GET /files, GET /files/screenshots, GET /files/recordings, GET /browser/downloads and PUT /files/{folder}/{name}/kept.

FILE-31. A listing or a read never opens a browser. Downloads read the workspace's record and, with no session open, are refused with no session is open in this workspace; a download lives only as long as the browser that took it, without asking the Grid. A Grid failure on a browser the record says is live is raised, not shown as an empty list.

FILE-32. A listing and a read of a download are scrubbed for the secrets in scope on the origins the call touched, because the site names a download (SEC-58).

Keeping

FILE-33. keep_file(uri) puts one file in Files and returns kept, from, uri, name, size and created. What it does depends on the section:

  • Files: the file stays; the result is its own entry. A name not in Files is a 400.
  • Screenshots: the file is read, claimed in Files under the first free name (FILE-9), then removed from Screenshots. If the removal fails or the screenshot is already gone, the Files copy is removed again and the call fails.
  • Recordings: the file is moved, not read into memory. The Files copy is claimed with a hard link (a copy where links cannot cross), then the source is removed. If the source cannot be removed the Files copy is removed and the call fails; a source replaced by a different file in between is left alone.
  • Downloads: the bytes are read from the Grid and written to Files under the download's name (renamed by FILE-8), replacing a file of that name already in Files. The download stays on the Grid.

FILE-34. A screenshot or recording that is not there is a 400 saying it may be kept already or cleared, and naming the folder's address.

FILE-35. Keeping is one-way for an agent. There is no tool to delete or clear a file. Deleting and clearing are admin actions (FILE-42 to FILE-44). The same Keep is offered over HTTP as PUT /files/{folder}/{name}/kept with folder one of screenshots, recordings or downloads, and to the admin (FILE-42).

Signed links

FILE-36. A file is opened without a header through one of four routes, keyed by what owns it:

Route Section Keyed by
/files/{session_id}/{name} Downloads the browser's Grid session id
/kept/{workspace}/{name} Files the workspace name
/screenshots/{workspace}/{name} Screenshots the workspace name
/recordings/{workspace}/{name} Recordings the workspace name

Each carries exp and sig as AUTH-23 describes, and grants that route's path alone (AUTH-27). The routes check the signature first, then say a file is not there.

FILE-37. A link works for link_ttl seconds (AUTH-24) and is the only credential the request needs, so a person can open it in a tab, paste it in a transcript or use it as an <img> source. A refused link is AUTH-26's 403. Reading the listing again gives a fresh link.

FILE-38. A Files, Screenshots or Recordings route answers 404 when the store is off, the name fails FILE-10, or the file is absent or not a regular file. A Downloads route answers 404 for a Grid scratch name (FILE-7) and when the Grid says the browser or the file is gone. Every other failure, and the wording of each answer, is AUTH-28's.

FILE-39. Files on disk are streamed from the descriptor that was checked, so a file replaced after the check is not served with the old size. They answer Range, so a player can seek. A download is read whole from the Grid and served as bytes.

FILE-40. Every served file carries:

  • Content-Disposition: inline with an ASCII filename (every other character and " and \ folded to _) and a percent-encoded filename*, so any name is fetchable;
  • Cache-Control: private, max-age=<seconds left on the link>, or 3600 for an unsigned link;
  • X-Content-Type-Options: nosniff;
  • a Content-Security-Policy by type.

FILE-41. The policy by type:

  • PNG, JPEG, GIF, WebP and AVIF: default-src 'none'; style-src 'unsafe-inline', not sandboxed;
  • video/* and audio/*: default-src 'none'; media-src 'self'; style-src 'unsafe-inline';
  • application/pdf: no policy, because Chrome's viewer does not load under a sandbox;
  • everything else, including SVG, HTML and an unknown type: sandbox, so a site's page opened inline cannot run script beside the admin UI.

Admin routes

FILE-42. GET /admin/workspaces/{key}/files returns the four sections for a workspace key, with the workspace's header. Downloads are listed only when the record's browser is alive on the Grid; otherwise Downloads is empty. With no store and no live browser every section is empty rather than an error, and a key that cannot be a directory name has no files.

POST /admin/workspaces/{key}/files/{folder}/{name}/keep keeps a screenshot, a recording or a download as FILE-33, and refuses another folder.

FILE-43. DELETE /admin/workspaces/{key}/files/{name} decides by name: downloads clears the Grid's store when the browser is alive (and succeeds without a call when it is not), screenshots and recordings delete every file in that folder and return cleared, and any other name deletes that one file from Files and returns deleted.

FILE-44. Clearing counts and deletes only listed files (FILE-11). The pending notes (FILE-55) are not files and survive a clear of Recordings, so a recording still on its way lands after it. Clearing Files is refused: Files is never cleared wholesale; delete one file.

Recordings

FILE-45. open_session(record=true) films the browser. The server asks the Grid to record (se:recordVideo: true) and names the video after the workspace (se:videoName, for a person reading the inbox; nothing matches on it). The Grid's recorder, in the node image, makes a fragmented MP4 of the node's display and ends it when the Grid session ends. One Grid session is one recording: a reopen after a reap is a new file.

FILE-46. record is explicit: its setting has no config, header or query source. A bare open_session() after end_browser does not inherit it, unlike every other remembered setting. A silent reopen after a reap replays it, unless recording has since been turned off. A raw se:recordVideo or se:videoName capability is refused in favour of record.

FILE-47. record=true is a 400 when recording.enabled is off (Recording is not set up on this server (recording.enabled is off). See the README's Recording section.), and when the browser is headless, whether asked now or remembered.

FILE-48. The open_session result carries recording: true|false. When the note (FILE-55) cannot be written, the browser stays open and the result carries recording_error. workspace://current reports recording: true while the live browser was opened with record.

FILE-49. Getting the video to the server is the operator's job. The operator makes the Grid's recordings arrive in one inbox directory (recording.dir, default <data>/recordings) by a shared volume, an upload to a drive, or a local folder. The server never receives an upload and never mounts the Grid. The inbox is the operator's: the server files from it and never cleans it.

FILE-50. The settings are:

Key Default Meaning
recording.enabled false The operator says the Grid's recordings reach the inbox
recording.dir <data>/recordings The inbox
recording.wait 600, at least 30 Seconds after a browser ends to wait for its file
recording.watch auto auto, events or poll
recording.poll 1000, at least 200 Milliseconds between looks when polling
recording.settle 10, at least 0 Seconds a finished file sits unchanged before it is filed

FILE-51. The server does not boot, naming the reason, when recording.enabled is set and:

  • data.dir is unset;
  • the inbox does not exist or is not readable, writable and searchable by the process;
  • the inbox is, holds or lies in <data>/workspaces.

It also does not boot with the old FLOW_DATA_DIR, or when a workspace folder is still at the top of data.dir instead of under workspaces/. It renames an old sessions/ folder to workspaces/ once; a flat workspace named sessions stays.

FILE-52. watch=auto polls when the inbox's mount is nfs, nfs4, cifs, smb3, smbfs, 9p, ceph, glusterfs or a fuse* type (read from /proc/self/mountinfo), and uses events otherwise, including where there is no /proc. Events do not see a file a network peer writes.

FILE-53. One collector per process (recordings/collector.py) files recordings. It runs only while a recording is owed: its task starts with the first expectation and ends when none is owed. It wakes on an inbox change and on a timer of 30 seconds, or recording.settle when that is shorter. It owns no browser and takes no session lock.

FILE-54. The browser opening writes a note the moment the Grid makes it, marked discard; the note is written again without the mark once the workspace holds the browser. A discard note's video is deleted, not filed, when it arrives, which covers a browser that lost a race to bind or whose open failed. The monitor reports the session's end to the collector (session.ended, any cause, a reap included).

FILE-55. A note is workspaces/<name>/recordings/.pending/<gridId>.json holding opened and ended in epoch milliseconds, browser, and, once done, filed or dropped. The notes are the queue, so a restart rebuilds it. A note that is not JSON or names no valid Grid id is skipped with a warning. A Grid id is 8 to 64 letters, digits and -, starting with a letter or digit.

FILE-62. A storage error reading a workspace's notes is a fault of that workspace, not a broken note. Every other workspace is read on, and only an unreadable data directory raises. The collector owes what it read, logs the rest once per streak and reads again each tick. Only bad JSON, a bad id or a non-file is skipped.

FILE-56. A sweep matches an .mp4 in the inbox whose path below it (folders and name) holds an owed Grid id, however deep. A name ending .partial, .part or .tmp is skipped. A path that holds more than one owed id matches none.

FILE-57. A recording is complete when its last 16 bytes are an mfro box whose size names an mfra box inside the file. A complete file is filed once its size and modification time have held for recording.settle seconds.

FILE-58. A file with no complete ending is filed as it is when its size and time have held for 60 seconds and its browser has ended. A live recording is never idle that long.

FILE-59. Filing moves the file into workspaces/<name>/recordings/ as rec-YYYYMMDD-HHMM.mp4 (UTC, from the note's opened), under the first free name (FILE-9), in a worker thread. The note is marked, then deleted; a note whose deletion fails is retried alone and never filed twice. Across filesystems the move is a copy and an unlink. Filing nudges the admin broadcast.

FILE-60. A recording whose file has not arrived recording.wait seconds after its browser ended is dropped: the note is deleted and one warning is logged naming the workspace and the time the browser opened. Nothing is shown. A file that arrives later is not claimed. A discard note that misses its deadline logs nothing.

FILE-61. The Recordings section lists filed videos only. There is no view of the inbox, the notes, or a recording in progress. Recordings are video/mp4 and answer Range (FILE-39).

Clone this wiki locally