Files and mounts

Besides its authored workspace (AGENTS.md and skills/), a workflow’s agent reads files from three places:

	Storage	Remote mount	Session files
Where the files live	The environment’s own storage	At the source, such as a SharePoint folder	The session’s folder, sessions/<id>/
How they get there	Uploaded on the Files page, or written by a turn	Kept at the source, or written by a turn	Chat attachments, uploads at a manual start, tool output, the agent’s own writes
Versioned	No	The definition is; the files are not	No
Reached by	Every session of the environment that is granted the folder	Every session that is granted the mount	That session only

A mount routes a Storage folder or a remote mount into a session’s workspace, and a workflow grants it per state. The Files page is where Storage and remote mounts are managed, and where the agent’s own files can be browsed; a session’s own files are read on the Sessions page.

The Files page

Files in the icon rail opens the Files page. A switch at its top shows the files of one of two views:

• Mounts, the default, is everything the environment’s sessions can mount. A write here reaches the next turn at once.
• Agent is the environment’s workspace as its draft holds it: AGENTS.md, workflows/, skills/, the agent icon, and the platform’s own entries. Every write here is a draft change, staged until Publish.

The page’s URL names the view (an Agent link opens the Agent view), and each view remembers the folder you had open, per browser, for each agent and environment.

The Mounts view

The Mounts view is one tree rooted at /. At the root, the environment’s Storage entries and its remote mounts share one table:

Column	Shows
Name	The entry, led by a glyph for a folder, a file kind, or the mount’s source
Size	A file’s size; empty for a folder
Source	For a remote mount, its source, connection and folder; empty for Storage
Mounted by	The workflows that mount the entry; empty when none does

The Mounted by cell is how you check that a grant took effect: placing a file in Storage does not make it readable to an agent, a grant does. The page has no search; browse into a folder to find a file. Each Storage entry can be renamed and copied from its row; a copy is read by every session from its next turn.

The Agent view

The Agent view has the same table, breadcrumb, preview and dialogs over the environment’s draft: browse any folder, preview and edit a text file, download, upload, create a folder, delete, and rename, copy or move an entry. Each write says it is staged: Publish makes it permanent and Discard brings the previous content back (see agents and environments).

Some entries are written by the surface that owns them and are read-only here, with the reason shown on the entry:

Entry	Written on
AGENTS.md and icon.png	The Agent page
workflows/	The workflow editor
Platform entries: .archmax/ (connections, settings, remote mount definitions) and .gitignore	The Connections and Settings pages, and the Mounts view

A platform entry can still be listed, previewed, downloaded and copied out; a name beginning with a dot is refused for anything you create.

Storage

Storage holds the reference data you give an agent: price lists, policies, catalogs. It sits outside versioning, which shapes how it behaves:

• A change reaches every session’s next turn as soon as it is saved, with no publish. Production and testing sessions read the same Storage.
• It is never a pending change and no version contains it. Publish, promote, restore and discard never read or write it.
• A deletion is final: there is no draft to discard it from and no version to restore it from.

The page header’s Upload puts one or more files into the Storage folder in view, the root included. New folder is offered inside a folder; at the root, Add mount with Local Folder is how a new top-level folder is made. An upload over an existing file asks you to confirm the replacement; a file above 20 MiB is refused.

Each Storage row ends with Download, Copy, Rename, Move and Delete:

• Activating a file opens its preview: Markdown is rendered, other text is shown verbatim, and a binary file offers its download instead. Edit opens the text for editing and Save writes it back; a preview the platform truncated cannot be edited, because saving it would cut the file short.
• Move relocates a file or a folder with everything inside it, or renames it in place. You walk to the destination folder; a destination that is already occupied is refused.
• Delete asks for confirmation, says that a folder takes its contents with it and that the deletion cannot be undone, and names the workflows that mount the entry.

Creating an environment from a parent copies the parent’s Storage as it is at that moment; after that the two are independent. Deleting an environment deletes its Storage with it, which is why that takes agent:delete, the agent’s Administrator (see Roles and groups). Promoting does not carry Storage: the promote dialog lists the folders the promoted workflows mount that the target does not have, so you can upload them on the target’s Files page.

Remote mounts

A remote mount names a connection of a mountable collection and one folder of it. The folder is served live: every listing and every read, on a turn or on the Files page, is a request to the source made at that moment. The platform stores no listing, no bytes and no index of it, so a file added at the source is visible on the next read, and an outage at the source is an error naming the mount, never stale content. Microsoft SharePoint is the mountable mount source; Google Drive is shown with a Preview tag and cannot be mounted yet.

Adding a remote mount

Add mount is offered at the root only. Its picker lists the sources: Local Folder first, which creates a top-level Storage folder, then Microsoft SharePoint. Choosing SharePoint shows the environment’s SharePoint connections as cards, with New connection opening the SharePoint connection form directly (see Connections). Pick a connection, walk its sites, drives and folders, and confirm; the Mount name defaults to the folder’s name in slug form and is the folder the agent reads the mount under.

A SharePoint connection can be delegated, signed in as a person, or app-only, made with your own Entra app (see Connections). A mount works the same over either: over a delegated connection it reaches the sites that person can open, over an app-only one the sites the app’s application permissions cover, and it keeps working when the person who signed in leaves.

The definition is written to .archmax/mounts/<slug>.yml in the environment’s draft. Unlike Storage it is authored content: a pending change until you publish, part of every version a session pins, and carried by promote. It is not inherited by a child environment, and it holds no secret and no file bytes: the connection’s credential is resolved when the mount is read.

A mount name and a top-level Storage name share one namespace, the agent’s workspace root, so neither can take the other’s name. The names workflows, skills and AGENTS.md, and the names the harness reserves at the workspace root such as scratchpad, are refused for both.

On the Files page

Inside a remote mount the page offers navigation, preview and download only; Upload and New folder are disabled. The breadcrumb carries a refresh control, and a folder the source cannot serve shows the source’s reason where the listing would be. At the root, a remote mount’s row offers two actions: rename, which warns that the workflows granting the old name keep it in their specs until you update them in the editor, and Remove mount, which names the granting workflows and touches nothing at the source.

What the agent can do on a remote mount

The turn’s prompt tells the agent the mount is live and browsed folder by folder. A glob or grep on the mount is refused, and a workspace-wide search skips it, so one remote mount does not fail a search of the rest. A file above 20 MiB is refused before it is fetched, and a long listing is cut short with a note saying so. A write is refused as read-only unless a grant asks the mount for read_write; then a file the agent writes lands at the source as a whole file. When a mount’s connection is missing, the turn still starts and every read of the mount reports it unavailable, naming the connection; validation warns about it, and so does the promote dialog when the target lacks the connection.

Granting mounts to states

A workflow declares its mounts in the mounts block of workflow.yaml, in the same shape as skills: mounts.allow_always reaches every state, a state’s mounts.allow adds to it, and mounts.forbid_always and a state’s mounts.forbid take a mount away. An entry is a Storage folder or a remote mount’s slug; a remote mount is granted whole. A workflow with no mounts block mounts only skills/ and AGENTS.md.

mounts:
  allow_always:
    - reference                               # read-only, in every state
    - { mount: exports, access: read_write }  # writable wherever it is granted

states:
  intake:
    mounts:
      allow: [contracts]                      # a remote mount, in this state only
  review:
    mounts:
      allow: [{ mount: exports, access: read }]  # reads exports, cannot write it here

A bare name asks for no write, and a mount no grant asks to write is read-only. Once any grant of the workflow asks a Storage folder or a remote mount for read_write, it is writable wherever it is granted, except in a state whose grant spells access: read. A mount a state is not granted is refused and hidden in that state. The harness documents the resolution in mounts.

A mount belongs to the workflow that grants it, in a child session too. A workflow that runs another one does not lend it its mounts: the child session reads and writes exactly what its own workflow grants, and its caller reaches none of the child’s mounts. A write needs a read_write grant of the workflow that writes, so one workflow’s read_write never opens a write through another workflow’s bare grant. The one exception is a denial: a caller’s mounts.forbid_always refuses that mount in every child session it runs, whatever the child grants. On the Files page, a mount is listed as mounted by the workflows that grant it, not by the workflows that run them.

In the editor, the workflow’s settings and each state have a File mounts section. Add mount opens Grant mounts, which lists the top-level Storage folders (marked Local Storage) and the remote mounts with their connections; each granted row has a Read / Read & write toggle. A grant is authored content and waits for a publish; the files it names do not.

A write by the agent into a writable Storage folder lands in Storage at once: the Files page shows it, no version holds a copy, and nothing restores it.

When a workflow is saved, an entry naming workflows, skills, AGENTS.md, a name the harness reserves, an absolute path or a path with .. is reported as an error; it mounts nothing. A folder Storage does not hold yet is only a warning, so you can declare a mount before uploading its files.

Session files

Every session has its own folder, sessions/<id>/ (the harness’s session zone), and it stays the same across the session’s turns, so a later turn reads what an earlier one wrote (see One id, one folder). Two subfolders matter most:

• attachments/ holds the files a member attaches to a chat message or uploads for a File input when starting the session by hand, and the files tools produce: an Activepieces action’s download, an MCP tool’s binary output, and files__download_file’s fetch of an https:// URL.
• scratchpad/ holds what the agent writes as it works. Its attachments/ receives the copies of files that cross a child session’s boundary: a type: file argument in the child, a type: file return in the caller.

A file is passed to a tool by its workspace path, such as attachments/report.pdf. A file on a mount is passed by the path ls shows, such as reference/terms.pdf, and read where it is; files__unpack_file, files__pack_files and files__create_presigned_url take files in the session’s folder only, so the agent copies a mounted file there with copy_file first. Every file exchanged this way is limited to 20 MiB. The agent reads a document such as a PDF with get_markdown, and sees an image it reads with read_file.

Reading a session’s files

On the Sessions page, a session’s detail panel shows a Files section in the turn summary, with no state selected: the folder’s tree, a text preview of the first 256 KB of a file, and a download for every file, binary ones included. Session files are read-only to you; no surface writes or deletes them. See Sessions.

A reply that links a file of its session, such as [Report](attachments/report.pdf), offers it as a download on the Chat page, in the editor’s chat card and in the session view’s transcript, and an embedded image such as ![Screenshot](attachments/screenshot.png) is shown. Every file of a chat also has an address under the chat’s path, /agents/<agent>/<environment>/chat/<chat>/<path>, which downloads the file after you sign in; opening a file link in a new tab uses it. A file in another member’s chat is not available.