AI sandboxes
Isolated environments for AI agents
Run AI coding agents in sandboxes with persistent storage, pre-configured tools, and security boundaries.
What are AI sandboxes
AI sandboxes combine two Windmill features to create secure, persistent environments for AI coding agents. Any script can become a sandbox with two annotations: // sandbox for process isolation via NSJAIL, and // volume: name path for persistent storage across runs. This pattern works for any agent that operates on a local filesystem: Claude Code, Codex, OpenCode, or custom agents.
Claude Code
Windmill includes a built-in Claude Code template using @anthropic-ai/claude-agent-sdk. Select it from the script editor to get a pre-configured sandbox with session persistence: the session ID is stored in the volume so the agent resumes where it left off. Pass instructions and skill files as input parameters to give the agent project-specific context.
Codex and custom agents
The same pattern works for OpenAI Codex (CLI) or any agent that operates on a local filesystem. Two annotations are all you need: // sandbox for isolation, and // volume: name path for persistence.
Persistent volumes
Files are synced to workspace object storage (S3, Azure Blob, GCS). Exclusive leasing prevents concurrent writes. Use dynamic volume names with $workspace or $args[userId] to scope storage per user or workspace. Up to 10 volumes per script, with an LRU cache up to 10 GB per worker.
Process isolation
Sandboxes use NSJAIL for filesystem isolation, network restrictions, and resource limits (CPU, memory, disk). The // sandbox annotation enables it per script, or it can be forced instance-wide for all jobs. For lighter workloads, PID namespace isolation is available as a faster alternative with lower overhead.
Resources and permissions
API keys and credentials are injected through Windmill resources, so secrets never appear in code. RBAC permissions control which scripts, flows, and resources each agent can access, and volume permissions (owner, read-only, read-write) scope storage access.
Observability
Every agent run is tracked with full observability: logs, execution history, and token usage for cost monitoring. Set up alerts on failures or cost thresholds, and audit agent activity across workspaces.
Read the docsFrequently asked questions
Build your internal platform on Windmill
Scripts, flows, apps, and infrastructure in one place.