A filesystem for AI agents with persistent shared storage gives agents a real POSIX directory that survives restarts and that other agents and your application can read and write at the same time. An agent’s files need to outlive its compute and remain available to the other parts of the application. Otherwise, useful work is tied to a temporary machine.
Archil provides this through disks that mount like a local filesystem, keep data durable across Availability Zones, and are reachable through an SDK and an S3-compatible API as well as from bash. An agent can work with files through familiar tools, while the application reads them without mounting a disk. The disk is the shared resource.
What a filesystem for AI agents with persistent shared storage needs
An agent filesystem needs both persistence and sharing. Persistence answers what happens when a run ends. Sharing answers how another agent or the application gets to the work while the system is running. Files that survive but remain isolated do not provide a common workspace, while files shared only on temporary compute still have an expiration problem.
A real POSIX filesystem adds the working interface. Agents need to use bash, git, Python and SQLite without adapters, rather than treat every file operation as a special integration project. At the same time, the application needs access that suits its own runtime, so a local mount cannot be the only way to reach the files.
Persistent: files that outlive the agent's compute
Agents run in short-lived compute, including serverless calls, sandboxes with timeouts and containers that get rescheduled. Anything written to that compute’s local disk goes with it. The result needs to exist independently of the environment that produced it.
A persistent agent filesystem separates those lifetimes by keeping files on storage that is independent of the compute. The next run, or a different agent, can then pick them up. This makes the storage the point of continuity between runs, rather than asking a short-lived environment to play that role. The agent’s process remains temporary, but its working files do not have to be.
Archil stores data redundantly across multiple Availability Zones once fsync returns. The POSIX interface lets agents use the file tools they already have, while fsync marks when the data has that redundant storage protection. These properties complement each other.
Shared: several agents and your app on the same files
Multi-agent systems also need a common place to read and write. One agent might write research notes, another read them, and the application show the results to a person. Each participant has a different job, but all need access to the relevant files. A handoff should not require the next participant to inhabit the previous agent’s compute. The shared disk gives that handoff a location independent of either agent.
Archil disks can be mounted by many clients at once. They are also reachable without a mount through the TypeScript and Python SDKs and an S3-compatible API. That gives the system different doors into the same workspace. A server or sandbox can use a local directory, while application code uses an SDK to read a file.
Visibility is the next part of that arrangement. Reads that reach the Archil disk server, including reads through the S3 API, see committed writes immediately, so the application does not read a stale copy through those reads. A mounted client can serve data from its own cache until that cache refreshes.
Archil publishes integrations for the AI SDK, Mastra and LangChain, giving agents built on those frameworks file tools directly on a disk. The integration connects the agent’s tools to the shared storage. It does not make the application become an agent. Application code can still read the file in its own way, keeping the agent’s work separate from how the application shows the result.
Example: an agent and your app sharing one disk
createDiskTools from @archildata/ai-sdk gives an agent tools to read, write and delete files, list directories, grep, and run bash on the disk. Bash runs through serverless execution, without a separate sandbox. The agent is asked to summarize every file in notes/ into notes/summary.md, and the application then reads that file from the same disk.
import * as archil from "disk";
import { generateText, isStepCount } from "ai";
import { createDiskTools } from "@archildata/ai-sdk";
const disk = await archil.getDisk(process.env.ARCHIL_DISK_ID!);
// The agent reads, writes, greps and runs bash on the disk
await generateText({
model: "anthropic/claude-sonnet-4.6",
prompt: "Summarize every file in notes/ into notes/summary.md",
tools: createDiskTools(disk),
stopWhen: isStepCount(30),
});
// Your app reads the same file, no mount needed
console.log(new TextDecoder().decode(await disk.getObject("notes/summary.md")));
The Disk object connects the two parts. createDiskTools(disk) exposes file operations to the agent, while disk.getObject("notes/summary.md") lets application code retrieve the output without mounting anything. The application does not need bash just because the agent can use it.
Servers and sandboxes can also mount that same disk as a local directory with the archil client. Several machines can mount it at once. The following command mounts a disk at /mnt/shared using conditional mode, with the write-access rules described in the next section.
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount dsk-0123456789abcdef /mnt/shared --region aws-us-east-1 --conditional
The mount adds a filesystem access path to the arrangement shown in the code. It does not replace the SDK access used by the application.
Choosing a sharing mode for multiple agents
The choice of sharing mode determines who can write where. Letting several clients mount a disk leaves open who can write where, because clients that read together may have different needs when they write. Archil has exclusive, shared and conditional modes for clients that mount a disk. The modes differ in who gets write access and how clients claim paths. The right distinction is not how many agents exist, but how their writing overlaps.
Exclusive mode is the default for archil mount. One client writes with local-disk performance, while other clients can mount read-only. This separates the writer from the readers.
Shared mode, turned on with --shared, lets many clients mount the disk. A client writes to paths it has claimed with archil checkout, and some operations, such as creating a file, claim the path automatically. Multiple clients can work on the disk, but a client’s write access follows its claims.
Conditional mode, enabled with --conditional, lets any client write anywhere that no other client has checked out. Creates, renames and deletes run on the server. If two clients write the same part of a file, the last write wins.
Writers to the same file need coordination. A common layout gives each agent its own directory to check out and provides a shared directory that everyone reads. This puts the division of work into the directory structure. Persistence protects the lifetime of the files, but write coordination governs what the agents put in them.
Where the data is stored
By default, a disk uses Archil-managed storage, with no bucket to set up. Its contents can be exported with any S3 client through the S3 API. That separates the initial storage setup from the ability to get the files out. Files in managed storage can be exported without mounting a filesystem. The S3-compatible interface provides another way to reach the disk’s contents, in addition to the application and agent access already described.
On paid plans, a disk can instead be synchronized with an existing S3, Google Cloud Storage or R2 bucket. Each file is stored as an ordinary object that any S3 tool can read. The bucket option changes the storage arrangement.
Disks run in AWS us-east-1, us-west-2 and eu-west-1, and GCP us-central1. They can be mounted from Linux, macOS and containers, with Kubernetes mounts available through the CSI driver. Location and access are distinct choices here. The regions describe where the disks run, while the mounting options describe the environments that can use them as a filesystem. SDK and S3-compatible access remain options for participants that do not mount the disk.
Checkpoints and branches add a different way to organize shared work. On disks that use Archil-managed storage, a team can snapshot a shared disk and fork it for parallel agent runs. Instead of putting every run into one live workspace, the team can use branches for parallel work from a snapshot. The compute performs the task, while the disk provides the durable working state that agents and the application can use.