docs: update volumes, AI sandbox, and changelog with latest source changes

- Volumes: add setup section (volume storage workspace setting), permissions
  model, volume name/target validation, max 10 volumes, agent worker support,
  create from UI, exclusive lease TTL correction, correct CE limit (50 MB/file)
- AI sandbox: update Claude Code template with token counting and prompt pattern
- Changelog: correct CE limit to 50 MB per file (no file count limit)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rubenfiszel

changelog/2026-02-26-volumes-sandbox-annotation-claude-sandbox/index.md

@@ -11,6 +11,6 @@ features:
   - 'AI sandbox: sandboxing + volumes pattern for running AI coding agents (Claude Code, Codex, OpenCode) with persistent state.'
   - 'Built-in Claude Code template using the Claude Agent SDK with volume-backed session persistence.'
   - 'Volumes UI in the Assets page for browsing, exploring, and deleting volumes.'
-  - 'Community Edition volume limits: 50 files, 50 MB per file.'
+  - 'Community Edition volume limit: 50 MB per file.'
 docs: /docs/core_concepts/ai_sandbox
 ---

docs/core_concepts/56_volumes/index.mdx

@@ -8,11 +8,16 @@ import DocCard from '@site/src/components/DocCard';
 
 Volumes provide persistent file storage that can be attached to [scripts](../../getting_started/0_scripts_quickstart/index.mdx) via code annotations. Files written to a volume during a job run are synced back to [object storage](../38_object_storage_in_windmill/index.mdx) and restored on the next run, enabling stateful workflows like caching, model storage, or agent memory.
 
-Volumes are an [Enterprise](/pricing) feature. On the Community Edition, volumes are limited to 50 files and 50 MB per file.
+Volumes are an [Enterprise](/pricing) feature. On the Community Edition, volumes are limited to 50 MB per file.
 
-## Prerequisites
+## Setup
 
-Volumes require a [workspace object storage](../38_object_storage_in_windmill/index.mdx#workspace-object-storage) (S3, Azure Blob, GCS, or filesystem) to be configured. Volume data is stored under the `volumes/` prefix in your workspace storage.
+Volumes require two things to be configured in your workspace:
+
+1. A [workspace object storage](../38_object_storage_in_windmill/index.mdx#workspace-object-storage) (S3, Azure Blob, GCS, or filesystem).
+2. A **volume storage** selection in the workspace settings under **Storage > Volume storage**. This can be set to the primary storage or any configured secondary storage. If volume storage is not selected, scripts with volume annotations will fail with an error.
+
+Volume data is stored under the `volumes/<workspace_id>/<volume_name>/` prefix in the selected storage.
 
 ## Declaring volumes
 
@@ -23,8 +28,10 @@ Volumes are declared with comment annotations at the top of your script. The syn
 ```
 
 Where:
-- `<name>` is the volume identifier (used as the storage key).
-- `<mount_path>` is the path where the volume will be available during execution. With [nsjail sandboxing](../../advanced/security_isolation/index.mdx), this can be an absolute path (`/tmp/data`) or a relative path. Without sandboxing, only relative paths are supported (e.g. `.claude`, `data/models`) — they are resolved relative to the job's working directory via a symlink.
+- `<name>` is the volume identifier. Must be 2–255 characters, start and end with an alphanumeric character, and contain only `a-z`, `A-Z`, `0-9`, `.`, `_`, or `-`.
+- `<mount_path>` is the path where the volume will be available during execution. With [nsjail sandboxing](../../advanced/security_isolation/index.mdx), this can be an absolute path (restricted to `/tmp/`, `/mnt/`, `/opt/`, `/home/`, `/data/` prefixes) or a relative path. Without sandboxing, only relative paths are supported (e.g. `.claude`, `data/models`) — they are resolved relative to the job's working directory via a symlink.
+
+A script can mount up to 10 volumes. Duplicate volume names or mount paths within the same script are not allowed.
 
 ### TypeScript / JavaScript
 
@@ -61,7 +68,7 @@ export async function main() {
 
 ### Multiple volumes
 
-You can mount multiple volumes on the same script:
+You can mount multiple volumes on the same script (up to 10):
 
 ```python
 # sandbox
@@ -96,35 +103,61 @@ When called with `env="prod"` in workspace `acme`, mounts volumes `acme-cache` a
 
 ## How it works
 
-1. **Before execution** - Windmill downloads the volume's files from object storage into a local directory, using a per-worker LRU cache (up to 10 GB) to skip unchanged files.
-2. **During execution** - The volume directory is bind-mounted (read-write) into the job's [nsjail](../../advanced/security_isolation/index.mdx) sandbox, or symlinked into the job directory when running without sandboxing.
-3. **After execution** - Changed and new files are synced back to object storage. Deleted files are removed from the remote. Volume metadata (size, file count) is updated.
+1. **Before execution** — Windmill acquires an exclusive lease on the volume, then downloads the volume's files from object storage into a local directory using a per-worker LRU cache (up to 10 GB). Files are compared by size and MD5 hash to skip unchanged files.
+2. **During execution** — The volume directory is bind-mounted (read-write) into the job's [nsjail](../../advanced/security_isolation/index.mdx) sandbox, or symlinked into the job directory when running without sandboxing.
+3. **After execution** — If the volume is writable, changed and new files are synced back to object storage. Deleted files are removed from the remote. Volume metadata (size, file count) is updated. The lease is released.
 
-Symlinks inside a volume are preserved: they are serialized to a `_symlinks.json` metadata file in object storage and restored on download.
+Symlinks inside a volume are preserved: they are serialized to a metadata file in object storage and restored on download.
 
 ### Exclusive leasing
 
-Only one job can use a given volume at a time. Windmill acquires an exclusive lease (30-second TTL, auto-renewed every 10 seconds) on each volume before downloading. If the volume is already leased by another worker, the job waits up to 2 minutes for the lease to be released.
+Only one job can use a given volume at a time. Windmill acquires an exclusive lease (60-second TTL, auto-renewed every 10 seconds) on each volume before downloading. If the volume is already leased by another worker, the job waits for the lease to be released.
+
+### Agent workers
+
+Volumes work with [agent workers](../28_agent_workers/index.mdx). Agent workers interact with volumes through an HTTP proxy API on the Windmill server — the same lease, download, sync-back, and permission logic applies.
+
+## Permissions
+
+Volumes support fine-grained permissions through Windmill's standard sharing model. You can share a volume with specific users or groups and set read-only or read-write access.
+
+- **Owner** — the user who created the volume (or whose job first created it). Has full read-write access and can delete the volume.
+- **Read-only** — the job can use the volume but changes are not synced back to object storage after execution.
+- **Read-write** — the job can both read from and write to the volume.
+- **No permission** — if a volume has permissions set and the job's user has no matching entry, the job will fail.
+
+Volumes with no permissions set (empty `extra_perms`) are accessible to all workspace users.
+
+Admins always have full access to all volumes.
+
+Permissions can be managed from the Volumes drawer in the [Assets](../52_assets/index.mdx) page using the share button.
 
 ## Managing volumes
 
-Volumes are auto-created when a job with a volume annotation runs for the first time. You can view and manage volumes from the [Assets](../52_assets/index.mdx) page, where volumes appear as `volume://name`.
+### Creating volumes
+
+Volumes can be created in two ways:
+
+- **Automatically** — when a job with a volume annotation runs and the volume doesn't exist yet, it is created with the job's user as owner.
+- **Manually** — from the Volumes drawer in the [Assets](../52_assets/index.mdx) page using the "New volume" button.
 
-Each volume entry tracks:
-- File count and total size
-- Created by (user who first triggered a job with this volume)
-- Last used timestamp
+### Exploring and deleting
 
-Workspace admins can delete volumes from the UI. Deleting a volume removes its metadata from the database.
+From the Volumes drawer you can:
+
+- View metadata: file count, total size, owner, last used timestamp.
+- Explore files in the volume using the S3 file browser.
+- Share the volume and manage permissions.
+- Delete the volume (owner, users with write permission, or admins). Deleting removes both the database metadata and all files from object storage. A volume that is currently leased by a running job cannot be deleted.
 
 <!-- TODO: add screenshot of the Volumes drawer from the Assets page showing a list of volumes with their metadata -->
 
 ## Volumes and sandboxing
 
 Volumes work with both sandboxed ([nsjail](../../advanced/security_isolation/index.mdx)) and non-sandboxed execution, but the mount path behavior differs:
 
-- **With nsjail (sandbox)** - The volume directory is bind-mounted read-write at the declared mount path inside the sandbox. Both absolute (`/tmp/data`) and relative paths work. Relative paths are resolved relative to the nsjail working directory (`/tmp/bun` for Bun/TypeScript, `/tmp/deno` for Deno, `/tmp` for Python and others).
-- **Without nsjail** - Only relative mount paths are supported. Windmill creates a symlink from the job directory to the volume's local directory. An environment variable (`WM_VOLUME_<NAME>`) is also set pointing to the local directory.
+- **With nsjail (sandbox)** — The volume directory is bind-mounted read-write at the declared mount path inside the sandbox. Both absolute (restricted to `/tmp/`, `/mnt/`, `/opt/`, `/home/`, `/data/`) and relative paths work. Relative paths are resolved relative to the nsjail working directory (`/tmp/bun` for Bun/TypeScript, `/tmp/deno` for Deno, `/tmp` for Python and others).
+- **Without nsjail** — Only relative mount paths are supported. Windmill creates a symlink from the job directory to the volume's local directory.
 
 You can combine volumes with the [`sandbox` annotation](../../advanced/security_isolation/index.mdx#sandbox-annotation) to enable per-script sandboxing, which is required if you need absolute mount paths:
 
@@ -136,6 +169,12 @@ export async function main() {
 }
 ```
 
+<DocCard
+  title="AI sandbox"
+  description="Run AI coding agents with sandboxing and persistent volumes"
+  href="/docs/core_concepts/ai_sandbox"
+/>
+
 <DocCard
   title="Security and process isolation"
   description="Sandbox annotation and nsjail configuration"

docs/core_concepts/58_ai_sandbox/index.mdx

@@ -72,12 +72,19 @@ export async function main(anthropic: RT.Anthropic, agent_instructions?: AgentIn
   }
 
   const isResume = !!sessionId;
-  const prompt = "what day are we, what is the current gitlab price";
+
+  // You can hardcode the prompt or pass it as input.
+  // AgentInstructions can contain a CLAUDE.md where to put the bulk of the instructions as well.
+  const prompt = !isResume
+    ? "What is the fastest OSS workflow engine?"
+    : "What did I ask you before?";
 
   process.env.ANTHROPIC_API_KEY = anthropic.apiKey;
 
   let response = "";
   let newSessionId: string | undefined;
+  let tokenCount = 0;
+  const seenIds = new Set<string>();
 
   for await (const msg of query({
     prompt,
@@ -93,6 +100,13 @@ export async function main(anthropic: RT.Anthropic, agent_instructions?: AgentIn
       newSessionId = msg.session_id;
     }
     if (msg.type === "assistant") {
+      const msgId = msg.message.id;
+      if (!seenIds.has(msgId)) {
+        seenIds.add(msgId);
+        tokenCount += msg.message.usage.input_tokens + msg.message.usage.output_tokens;
+        console.log(`${tokenCount} tokens`);
+      }
+
       response += msg.message.content
         .filter((b: any) => b.type === "text")
         .map((b: any) => b.text)