Windows Sandboxes

Daytona provides Windows sandboxes for AI agents that need a Windows operating system. Each Windows sandbox runs its own Windows kernel with a dedicated filesystem, network stack, and allocated vCPU, RAM, and disk.

Agents and developers can install software, run Windows applications, run commands in the command prompt or PowerShell, and control the desktop through Computer Use.

Use cases

Windows sandboxes are used when the software, the test, or the task requires Windows.

• Computer-use agents on Windows: an agent operates Windows applications through screenshots, mouse and keyboard input, and the accessibility tree with Computer Use, for tasks that exist only in Windows software.
• Windows-only software: programs, installers, and command-line tools that have no Linux version run in an isolated machine instead of on a shared Windows server.
• Build and test on Windows: code, scripts, and installers are built or tested on a clean Windows machine for each run, so results do not depend on leftover state.
• PowerShell and automation: PowerShell scripts and Windows administration tasks run against a real Windows installation before they reach production machines.
• Evaluation and reinforcement learning (RL): each test case or episode gets an identical Windows machine, started from the base snapshot or from a filesystem snapshot you prepared.
• Long-lived agent sessions: a Windows sandbox pauses when the agent goes idle and resumes with its processes and memory intact.
• Branching from a running state: a Windows sandbox is forked to try several approaches from the same point. Each fork gets its own copy of the filesystem and memory.

Create a Windows sandbox

Create a Windows sandbox.

from daytona import Daytona, CreateSandboxFromSnapshotParams

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="windows-small"))

Filesystem snapshot

A filesystem snapshot, also called a cold snapshot, saves the filesystem of a stopped Windows sandbox. A snapshot without the include memory option is a filesystem snapshot.

from daytona import Daytona, CreateSandboxFromSnapshotParams

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="windows-small"))

# Write a file to the filesystem
sandbox.fs.upload_file(b"done", "setup.txt")

# A filesystem snapshot requires a stopped sandbox
sandbox.stop()
sandbox.create_snapshot("my-windows-snapshot")

# A sandbox created from the snapshot starts with the same filesystem
new_sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="my-windows-snapshot"))
content = new_sandbox.fs.download_file("setup.txt")
print(content.decode())  # done

Memory snapshot

A memory snapshot, also called a hot snapshot, saves the filesystem and memory of a started Windows sandbox. A sandbox created from a memory snapshot starts with its processes and open applications already running.

curl 'https://app.daytona.io/api/sandbox/{sandboxIdOrName}/snapshot' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "name": "my-windows-hot-snapshot",
  "includeMemory": true
}'

Filesystem persistence

Filesystem persistence keeps the contents of a sandbox's disk: files, installed programs, cloned repositories, and build artifacts. A sandbox with a preserved filesystem starts with its environment intact, with nothing to reinstall or rebuild.

Windows sandboxes preserve their filesystem across stop and start and filesystem snapshots created from a sandbox. An ephemeral sandbox is deleted on stop, so its filesystem is not kept.

from daytona import Daytona, CreateSandboxFromSnapshotParams

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="windows-small"))

# Write a file to the filesystem
sandbox.fs.upload_file(b"done", "setup.txt")

# Stop clears memory and moves the filesystem to nearby storage
sandbox.stop()

# Start restores the filesystem and boots the sandbox
sandbox.start()
content = sandbox.fs.download_file("setup.txt")
print(content.decode())  # done

Memory persistence

Memory persistence keeps the runtime state of a sandbox: running processes, open applications, and everything loaded in RAM. A sandbox with preserved memory continues from the point it was frozen, with processes still running, instead of starting from a clean boot.

Windows sandboxes preserve their memory across pause and resume, memory snapshots created from a sandbox, and forks. Memory state is cleared on every stop.

from daytona import Daytona, CreateSandboxFromSnapshotParams, SessionExecuteRequest

daytona = Daytona()
sandbox = daytona.create(CreateSandboxFromSnapshotParams(snapshot="windows-small"))

# Start a process that runs in the background
sandbox.process.create_session("keepalive")
response = sandbox.process.execute_session_command(
    "keepalive",
    SessionExecuteRequest(command="ping -n 3600 127.0.0.1", run_async=True),
)

# Pause keeps the filesystem and memory
sandbox.pause()

# Start resumes every process from the point where the sandbox paused
sandbox.start()
command = sandbox.process.get_session_command("keepalive", response.cmd_id)
print(command.exit_code)  # None: the process is still running

Desktop

Windows sandboxes support Computer Use on the Windows desktop: screenshots, mouse and keyboard input, display and window information, the accessibility tree, and screen recordings.

Shell

The toolbox runs commands with the Windows command prompt by default. To run commands with another shell, such as Windows PowerShell or PowerShell 7, set the following environment variable in the sandbox. The toolbox looks the value up on the PATH and falls back to the command prompt if it is not found. If the toolbox cannot find the command prompt, it uses Windows PowerShell.

The command prompt rejects command lines longer than 8191 characters. For longer commands, use a session command or PowerShell.

Lifecycle

Every Windows sandbox moves through a lifecycle. A Windows sandbox can have several different states. Each state reflects the status of your sandbox. A Windows sandbox transitions between states in response to user actions, or automatically when one of its timeouts elapses.

Wait for state

Wait until a Windows sandbox reaches the started or stopped state.

sandbox.wait_for_sandbox_start(timeout=60)
sandbox.wait_for_sandbox_stop(timeout=60)

Stop / start

Stop a sandbox. The sandbox moves to the stopped state when shutdown completes. While a stop is in progress, the sandbox is in the stopping state and does not accept new requests.

Stopping shuts down the virtual machine while preserving the filesystem. Memory state is cleared. To preserve running process state without consuming CPU, use pause / resume.

Start a sandbox.

1. Go to Daytona Sandboxes ↗
2. Click the stop icon ⏹ next to the sandbox you want to stop
3. Click the start icon ▶ next to the sandbox you want to start

sandbox.stop()
sandbox.start()

Pause / resume

Pause and resume a sandbox.

The filesystem and memory state are preserved, and CPU is no longer consumed.

sandbox.pause()

# Resume the paused sandbox
sandbox.start()

Fork

Fork a sandbox.

Forking creates a duplicate of a Windows sandbox's filesystem and memory state in a new sandbox. The forked sandbox is fully independent: it can be started, stopped, and deleted without affecting the original.

Daytona tracks the parent-child relationship in a fork tree, so you can trace a fork's lineage back to the sandbox it was created from. You can fork a fork to build branches. The parent sandbox cannot be deleted while it has active fork children.

1. Go to Daytona Sandboxes ↗
2. Click the three-dot menu (⋮) next to the started Windows sandbox you want to fork
3. Select Fork

forked = sandbox.fork(name="my-forked-sandbox")

Delete

Delete a sandbox.

1. Go to Daytona Sandboxes ↗
2. Click Delete next to the sandbox you want to delete

sandbox.delete()

# Block until the sandbox is deleted
sandbox.delete(timeout=60, wait=True)

Timeouts

Daytona stops, pauses, or deletes a Windows sandbox when a timeout elapses. Each timeout is set in minutes. Zero disables auto-stop, auto-pause, and wall-clock TTL. Zero does not disable auto-delete: auto-delete set to zero deletes the sandbox as soon as it stops. To disable auto-delete, set it to -1. Windows sandboxes do not support auto-archive.

Auto-pause

The auto-pause interval sets the amount of time after which an idle VM sandbox is automatically paused. Auto-pause applies only to VM sandboxes and is mutually exclusive with the auto-stop interval: at most one of the two intervals may be non-zero. Ephemeral sandboxes cannot have auto-pause enabled.

The interval is set in minutes:

• 0: disables the auto-pause functionality
• if neither auto-pause nor auto-stop is set, non-ephemeral sandbox classes that support pausing default to an auto-pause interval of 60 minutes with auto-stop disabled

The sandbox pauses after no new events occur for the specified interval. Events include sandbox state changes and interactions with the sandbox through the SDK. Interactions through sandbox previews do not reset the timer.

from daytona import CreateSandboxFromSnapshotParams

sandbox = daytona.create(CreateSandboxFromSnapshotParams(
    snapshot="windows-small",
    auto_pause_interval=60,
))

# Change the interval on an existing sandbox
sandbox.set_auto_pause_interval(30)

Wall-clock TTL

The wall-clock TTL (time-to-live) sets a hard upper bound on how long a sandbox may exist. Unlike the auto-delete interval, which counts time only while the sandbox is stopped, TTL runs as wall-clock time from creation (or from the moment you last set it) and destroys the sandbox in any state: started, stopped, paused, or archived.

Set ttl_minutes when creating a sandbox, or update it later. The value is in minutes:

• 0: disables the TTL
• if not set, the sandbox has no TTL deadline

Calling set_ttl after creation resets the deadline from the current moment. Use wall-clock TTL for agent sessions, CI jobs, and any sandbox that must not outlive a fixed deadline.

sandbox = daytona.create(CreateSandboxFromSnapshotParams(
    snapshot="windows-small",
    ttl_minutes=120,
))

# Reset the deadline to 60 minutes from now
sandbox.set_ttl(60)