What a Snapshot Stores

You do not want secrets, git metadata, or install trees in durable storage. The default snapshot policy excludes those paths. When a capture or restore finds an unsafe filesystem entry, it stops.

Portable snapshots store regular files and directories only. When a capture or restore finds a symlink, an executable file, or a special filesystem entry, it fails with SandboxSnapshotError code SANDBOX_SNAPSHOT_UNSUPPORTED_ENTRY. Exclude scripts, hooks, and other executable files in policy.exclude. An executable bit on a regular file stops the whole capture or restore.

Default exclusions#

The default policy excludes these path segments at every depth:

• .git
• node_modules
• .env*

It also excludes these exact paths:

• The projection marker, .tanstack-projected-<workspaceHash>, at the workspace root only.
• CLAUDE.md and GEMINI.md at the workspace root.
• Direct .claude/skills/<name>, .codex/skills/<name>, and .grok/skills/<name> paths.

These exclusions use paths for regular files and copied files too.

Replace the default policy#

To keep only some files, or one file, see Pick Which Files to Keep. If you pass only include or only redact, the default exclusions stay in place. If you pass exclude, copy defaultSandboxSnapshotPolicy() first. Then add your rules.

import { defaultSandboxSnapshotPolicy } from '@tanstack/ai-sandbox'

const policy = {
  ...defaultSandboxSnapshotPolicy(),
  redact({ bytes }: { bytes: Uint8Array }) {
    return bytes
  },
}

When you create the snapshots object, pass policy. See Keep Files After Reload.

The exact projection marker for the workspace stays protected. A custom policy cannot capture or restore that marker.

Secrets#

Resolved secret values are replaced with zero bytes before the content is hashed or stored.

Restore safety#

An invalid manifest, a missing blob, or changed blob content stops the restore before it writes the workspace. The failed private sandbox is then discarded. Your existing resumed sandbox stays unchanged.

See Providers for provider-native snapshot and resume support.