Quickstart

This page will walk you through how to set up an Archil disk and build a real agent with the AI SDK in less than 5 minutes that uses real tools, like bash, against your data. With Archil, you only pay for the infrastructure that you use, which means that this entire tutorial should fit inside of our free plan. For this tutorial, let’s build an agent that writes a storybook for us, creates a nicely formatted PDF document of our book, and delivers an audit-log of every tool that it used to create the book — without the use of a separate sandbox.

This tutorial does not walk through mounting the Archil file system. If you already have a server you want to attach Archil to, see Mount on Linux (FUSE) (or macOS / in a container).

Create an API key

Sign in to the Archil console, create an API key from the API keys page, and export it alongside a key for your model provider:

export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-east-1
export ANTHROPIC_API_KEY=sk-ant-...

Create your API key in the region closest to where your users are, for this tutorial, you need to use one of the Archil AWS regions where sandboxes are offered (aws-us-east-1, aws-us-west-2, or aws-eu-west-1); see Region availability.

Install dependencies

In your project directory, install the required dependencies for this tutorial:

npm install ai @ai-sdk/anthropic disk @archildata/ai-sdk

Create your agent's workspace

Archil provides the file system workspace for agents to store files, manipulate context, and run complex commands — while providing concurrent access to that workspace from your web application for humans. Each Archil account supports an unlimited number of file systems so we recommend making one for each agent that you plan to run. Make one for our tutorial agent:

npx disk create tutorial-agent-disk

import * as archil from "disk";

const { disk: agentDisk } = await archil.createDisk({ name: "tutorial-agent-disk" });

The result includes a token that you can use to mount the disk directly. You do not need it for this tutorial.

If you have an existing S3 or GCS bucket you’d like the agent to work against, you can specify it as a data source when creating your disk — see S3 Object Storage. When specifying a data source, your disk will mirror the contents of your bucket.

Build the agent

Let’s build our agent to now write us a short story. We use a ToolLoopAgent from the AI SDK to iteratively call tools until we accomplish our goal. We’ll go ahead and give the agent some instructions to use Archil and connect our disk as a set of tools in conditional mode.

import { anthropic } from "@ai-sdk/anthropic";
import { ToolLoopAgent } from "ai";
import { createDiskTools } from "@archildata/ai-sdk";

// Mount the disk as a workspace, opting the agent into our new,
// conditional mode semantics.
const workspace = archil.workspace({
  workspace: { disk: agentDisk, conditional: true },
});

const agent = new ToolLoopAgent({
  model: anthropic("claude-sonnet-5"),
  instructions: [
    "You are a writing assistant. Save your work as you go.",
    "Everything happens in /mnt/archil/workspace — use that path for bash and for the file tools.",
    "Each bash command runs in a fresh container, so anything you install belongs in the workspace if you want it next time.",
  ].join(" "),
  tools: createDiskTools(workspace),
});

await agent.generate({
  prompt: "Write a short story, format it nicely and save it as story.pdf",
});

That’s the whole integration. createDiskTools automatically gives the agent a set of tools to manipulate data on the disk without a separate sandbox which includes: read/write/delete files, run bash, glob, and grep.You can view your story in the Archil console, or by downloading the contents of the file:

import { writeFile } from "node:fs/promises";

await writeFile("story.pdf", await workspace.getObject("workspace/story.pdf"));

Record an audit log

Next, let’s extend our agent to make it ready for production by building an audit log of each tool call that was made while it ran. We can easily build an append-only log on Archil by using the AppendObject function of our extended S3 API.We can use the onToolExecutionEnd lifecycle hook in the AI SDK to record each tool call as it happens.Replace the agent.generate line in your code with the following:

const auditPath = `.audit/${Date.now()}.jsonl`;

await agent.generate({
  prompt: "Write a short story, format it nicely and save it as story.pdf",
  onToolExecutionEnd: async ({ toolCall, toolOutput, toolExecutionMs }) => {
    const entry = {
      tool: toolCall.toolName,
      input: toolCall.input,
      ms: Math.round(toolExecutionMs),
      result: toolOutput.type === "tool-result" ? toolOutput.output : toolOutput.error,
    };
    await agentDisk.appendObject(auditPath, `${JSON.stringify(entry)}\n`);
  },
});

Now, you can view your audit log by reading the contents of the auditPath file.

const audit = new TextDecoder().decode(await agentDisk.getObject(auditPath));
for (const line of audit.trim().split("\n")) {
  const { tool, ms, input } = JSON.parse(line);
  console.log(`${tool.padEnd(11)} ${String(ms).padStart(6)}ms  ${JSON.stringify(input).slice(0, 60)}`);
}

Which will output the audit log entries to the console that look like this:

run_bash       202ms  {"command":"which pandoc wkhtmltopdf weasyprint pdflatex ens...
run_bash      3571ms  {"command":"pip install --quiet reportlab 2>&1 | tail -20; e...
write_file      55ms  {"path":"/mnt/archil/workspace/story.txt","content":"The Lig...
run_bash      3241ms  {"command":"cd /mnt/archil/workspace && pip install --quiet...

You now know the basics of how to build agents with Archil with persistent disks that can scale to any size, have multiple agents work in parallel, and provide strong-consistency for human clients who might interact using a web application via our S3-compatible API.

Next steps

AI SDK integration

Mount several disks as one workspace, and scope what the agent can reach.

Serverless execution

The runtime behind run_bash — fan out across containers, compose disks, no lifecycle to manage.

Multi-agent systems

Branch a disk per agent, run them in parallel, and keep the best result.

Persistent sandboxes

Keep a sandbox warm across tool calls when the agent needs a long-lived machine.

Mount to a Linux server

Use the same disk as a POSIX filesystem from your own machines.

Pricing

View Archil pricing and plan details.

Getting started

Compute

Concepts

Data Sources

Details

Administration

Protocols

Reference

Legal

Next steps

AI SDK integration

Serverless execution

Multi-agent systems

Persistent sandboxes

Mount to a Linux server

Pricing

​Next steps

AI SDK integration

Serverless execution

Multi-agent systems

Persistent sandboxes

Mount to a Linux server

Pricing

Next steps