Isolation Strategies

A3S Code provides four isolation layers to prevent agent operations from affecting files or system resources outside the intended scope.

Isolation Layers
  ├─ Workspace Boundary   ← File ops confined to the session directory (always on)
  ├─ File Version History ← Auto-snapshot before writes; diff and restore any version
  ├─ Git Worktree         ← Agent works on an isolated branch; discard with one command
  └─ MicroVM Sandbox      ← bash runs inside an isolated VM (host app supplies BashSandbox impl)

Workspace Boundary

All file operations (read, write, edit, glob, grep) are confined to the directory specified when creating the session. Attempts to access paths outside the workspace are intercepted immediately — no retry, no path disclosure to the LLM.

This boundary is always active and cannot be disabled through configuration.

File Version History

Whenever the agent executes write, edit, or patch, A3S Code automatically captures a snapshot of the file before the modification. Snapshots are stored in session memory and support version listing, diff generation, and restore.

Snapshot Triggers

Tool	Snapshot Taken
`write`	Before overwriting
`edit`	Before string replacement
`patch`	Before applying patch

Using File History

File version history APIs (listFileVersions, diffFileVersions, restoreFileVersion) are available in the Rust SDK. The TypeScript SDK exposes file operations through the LLM tool calls (read, write, edit) rather than direct session methods.

VersionSummary Fields (Rust SDK)

Prop

Type

File history is session-scoped in-memory storage and is not persisted after the session ends. For cross-session change tracking, use the Git Worktree approach instead.

Git Worktree

The git_worktree tool lets the agent work on an isolated Git worktree (branch). All agent changes stay on the isolated branch — the main branch is completely unaffected. If an experiment fails, remove the worktree with a single command to discard all changes.

Workflow

Create worktree — establish an isolated workspace on a new branch

Work in isolation — all agent file changes are committed to this branch

Review results — inspect changes, decide to merge or discard

Merge or discard — if satisfied, merge; if not, remove the entire worktree

Example

// Create isolated worktree
await session.callTool('git_worktree', {
  command: 'create',
  branch: 'agent/refactor-auth',
  path: '/tmp/agent-worktrees/refactor-auth',
  newBranch: true,
  base: 'main',
});

// Create session pointing at the worktree
const isolatedSession = agent.session('/tmp/agent-worktrees/refactor-auth');

// All changes on isolated branch
const result = await isolatedSession.send('Refactor auth module to use JWT');

// List all worktrees
const list = await session.callTool('git_worktree', { command: 'list' });

// Discard if not satisfied
await session.callTool('git_worktree', {
  command: 'remove',
  path: '/tmp/agent-worktrees/refactor-auth',
});

# Create isolated worktree
session.call_tool("git_worktree", {
    "command": "create",
    "branch": "agent/refactor-auth",
    "path": "/tmp/agent-worktrees/refactor-auth",
    "new_branch": True,
    "base": "main",
})

# Create session pointing at the worktree
isolated_session = agent.session("/tmp/agent-worktrees/refactor-auth")

# All changes on isolated branch
result = isolated_session.send("Refactor auth module to use JWT")

# Discard entire worktree if not satisfied
session.call_tool("git_worktree", {
    "command": "remove",
    "path": "/tmp/agent-worktrees/refactor-auth",
})

git_worktree Parameters

Prop

Type

See Git Worktree Example for a full walkthrough.

MicroVM Sandbox

When bash tool commands need to run inside an A3S Box MicroVM instead of the host process, the host application supplies a concrete BashSandbox implementation via SessionOptions::with_sandbox_handle(). The workspace directory is mounted read-write at /workspace inside the VM.

No Cargo feature flag is required. a3s-code-core ships the BashSandbox trait as an open extension point. The host application (e.g. SafeClaw) provides the concrete sandbox implementation.

Rust — wiring in a custom sandbox

use a3s_code::{sandbox::BashSandbox, agent_api::SessionOptions};
use std::sync::Arc;

// Any type that implements BashSandbox can be supplied here.
// SafeClaw ships an a3s-box–backed implementation; you can provide your own.
let opts = SessionOptions::default()
    .with_sandbox_handle(Arc::new(my_sandbox_impl));

let session = agent.session("/project", opts).await?;

BashSandbox trait

#[async_trait]
pub trait BashSandbox: Send + Sync {
    /// Execute a shell command inside the sandbox.
    async fn run(&self, command: &str, config: &SandboxConfig) -> Result<SandboxOutput>;
}

SandboxConfig Fields

Prop

Type

Networking is disabled by default (network: false). Enable only when the agent needs to run npm install, pip install, or similar network operations — and consider pairing it with a permission policy to restrict which commands can run.

Choosing an Isolation Strategy

Scenario	Recommended approach
Prevent reading files outside the project	Workspace boundary (always on)
Undo agent file writes	File version history
Agent works on an experimental branch	Git worktree
Isolate system side-effects of bash commands	MicroVM sandbox
High-security production environment	Git worktree + MicroVM sandbox

Isolation Strategies

On this page