Persistent Sandboxes Deep Dive

Persistent Sandboxes: The Auteryn Advantage

Auteryn sandboxes are persistent, isolated environments where your agents work. Unlike ephemeral containers that reset, our sandboxes remember everything—even across restarts.

Key Differentiator: While competitors use ephemeral environments that reset, Auteryn sandboxes persist indefinitely with automatic snapshots every 5 minutes.

What is a Sandbox?

A sandbox is a complete Linux environment where your agent executes tasks:

Full filesystem - Read, write, and manage files
Terminal access - Run any shell command
Browser - Automate web interactions
Network access - Call APIs and webhooks
Installed packages - Python, Node.js, system tools
Persistent state - Everything survives restarts

Think of it as a virtual computer in the cloud that your agent controls.

Architecture Overview

┌─────────────────────────────────────────┐
│         Auteryn Platform            │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────────────────────────┐  │
│  │     Your Agent                   │  │
│  │  - Instructions                  │  │
│  │  - Knowledge Base                │  │
│  │  - Tools & Integrations          │  │
│  └──────────────┬───────────────────┘  │
│                 │                       │
│                 ▼                       │
│  ┌──────────────────────────────────┐  │
│  │   Persistent Sandbox             │  │
│  │                                  │  │
│  │  ┌────────────────────────────┐ │  │
│  │  │  Filesystem                │ │  │
│  │  │  /home/agent/              │ │  │
│  │  │    ├── code/               │ │  │
│  │  │    ├── data/               │ │  │
│  │  │    └── output/             │ │  │
│  │  └────────────────────────────┘ │  │
│  │                                  │  │
│  │  ┌────────────────────────────┐ │  │
│  │  │  Terminal (bash)           │ │  │
│  │  │  $ python script.py        │ │  │
│  │  └────────────────────────────┘ │  │
│  │                                  │  │
│  │  ┌────────────────────────────┐ │  │
│  │  │  Browser (Chromium)        │ │  │
│  │  │  Headless automation       │ │  │
│  │  └────────────────────────────┘ │  │
│  │                                  │  │
│  │  Auto-snapshot every 5 minutes  │  │
│  └──────────────────────────────────┘  │
│                                         │
└─────────────────────────────────────────┘

Key Features

1. True Persistence

The Problem with Ephemeral Environments:

Most AI agent platforms use containers that reset:

Work is lost when the session ends
Agents start from scratch every time
No continuity between tasks
Can’t build on previous work

Auteryn Solution:

Sandboxes persist indefinitely:

Files remain between sessions
Installed packages stay installed
Configuration persists
Agents build on previous work

Ephemeral (Others)
Persistent (Auteryn)

# Session 1
$ pip install pandas
$ python analyze.py
# Creates output.csv

# Session 2 (later)
$ ls
# output.csv is GONE
$ pip list
# pandas is NOT installed
# Have to start over

# Session 1
$ pip install pandas
$ python analyze.py
# Creates output.csv

# Session 2 (later)
$ ls
# output.csv is STILL THERE
$ pip list
# pandas is STILL installed
# Continue where you left off

2. Automatic Snapshots

Every 5 minutes, Auteryn automatically snapshots your sandbox:

No manual intervention - Happens automatically
Zero performance impact - Incremental snapshots
Unlimited history - Keep snapshots as long as needed
Instant restore - Roll back to any point in time

Use Cases:

Undo mistakes
Debug issues
Compare states
Recover from errors

# View available snapshots
agent.list_snapshots()
# [
#   "2026-04-02T10:00:00Z - Auto",
#   "2026-04-02T10:05:00Z - Auto",
#   "2026-04-02T10:10:00Z - Manual: before-deployment"
# ]

# Restore to a specific snapshot
agent.restore_snapshot("2026-04-02T10:10:00Z")

3. Manual Snapshots

Create snapshots at critical moments:

# Before risky operation
agent.create_snapshot("before-database-migration")

# Try the operation
result = agent.run("migrate_database.py")

# If something goes wrong
if not result.success:
    agent.restore_snapshot("before-database-migration")

Best Practices:

Snapshot before deployments
Snapshot before major changes
Snapshot after successful milestones
Name snapshots descriptively

4. Time-Travel Debugging

Go back in time to debug issues:

# Something broke at 10:30 AM
# Restore to 10:25 AM (before the issue)
agent.restore_snapshot("2026-04-02T10:25:00Z")

# Investigate what happened
agent.run("cat /var/log/agent.log")

# Try a different approach
agent.run("python fixed_script.py")

Sandbox Lifecycle

Creation

When you create an agent, a sandbox is automatically provisioned:

agent = Auteryn.create_agent(
    name="my-agent",
    instructions="...",
    sandbox_config={
        "size": "medium",  # small, medium, large
        "region": "us-east-1",
        "auto_shutdown": True,
        "shutdown_after": "1h"  # Auto-shutdown after 1 hour idle
    }
)

Sandbox Sizes:

Size	CPU	RAM	Disk	Use Case
Small	1 core	2 GB	10 GB	Light tasks, testing
Medium	2 cores	4 GB	20 GB	Most use cases
Large	4 cores	8 GB	50 GB	Heavy computation

Auto-Shutdown

Save costs with automatic shutdown:

Idle detection - Shuts down after inactivity
Instant wake - Resumes in <5 seconds
State preserved - Everything persists
No data loss - Automatic snapshot before shutdown

# Configure auto-shutdown
agent.configure_sandbox(
    auto_shutdown=True,
    shutdown_after="30m"  # Shutdown after 30 minutes idle
)

Manual Control

Control sandbox lifecycle manually:

# Start sandbox
agent.sandbox.start()

# Stop sandbox (state preserved)
agent.sandbox.stop()

# Restart sandbox
agent.sandbox.restart()

# Check status
status = agent.sandbox.status()
# "running", "stopped", "starting", "stopping"

Filesystem Structure

Default sandbox filesystem:

/home/agent/
├── code/           # Your code and scripts
├── data/           # Input data and files
├── output/         # Generated outputs
├── logs/           # Agent logs
├── .env            # Environment variables
└── snapshots/      # Snapshot metadata

Best Practices:

Keep code in /home/agent/code/
Store data in /home/agent/data/
Write outputs to /home/agent/output/
Use .env for secrets (encrypted at rest)

Security & Isolation

Network Isolation

Each sandbox is network-isolated:

Outbound allowed - Can call external APIs
Inbound blocked - No direct access from internet
VPC integration - Connect to your private network (Enterprise)
Firewall rules - Configure allowed destinations

Filesystem Isolation

Sandboxes are completely isolated:

No cross-sandbox access - Agents can’t see each other
Encrypted at rest - All data encrypted (AES-256)
Encrypted in transit - TLS 1.3 for all connections
Secure deletion - Data wiped on sandbox deletion

Resource Limits

Prevent resource exhaustion:

agent.configure_sandbox(
    cpu_limit="2 cores",
    memory_limit="4 GB",
    disk_limit="20 GB",
    network_bandwidth="100 Mbps"
)

Advanced Features

Shared Volumes

Share data between agents:

# Create shared volume
volume = Auteryn.create_volume(
    name="shared-data",
    size="10 GB"
)

# Mount in multiple agents
agent1.sandbox.mount_volume(volume, "/mnt/shared")
agent2.sandbox.mount_volume(volume, "/mnt/shared")

Custom Images

Use custom Docker images:

agent = Auteryn.create_agent(
    name="my-agent",
    sandbox_config={
        "image": "my-registry/my-image:latest",
        "pull_credentials": {
            "username": "...",
            "password": "..."
        }
    }
)

GPU Support (Enterprise)

Enable GPU for ML workloads:

agent.configure_sandbox(
    gpu=True,
    gpu_type="nvidia-t4",
    gpu_count=1
)

Monitoring & Observability

Resource Usage

Monitor sandbox resource consumption:

metrics = agent.sandbox.metrics()
# {
#   "cpu_usage": "45%",
#   "memory_usage": "2.1 GB / 4 GB",
#   "disk_usage": "8.5 GB / 20 GB",
#   "network_in": "125 MB",
#   "network_out": "89 MB"
# }

Logs

Access sandbox logs:

# Stream logs in real-time
for log in agent.sandbox.logs(follow=True):
    print(log)

# Get last 100 lines
logs = agent.sandbox.logs(tail=100)

Alerts

Set up alerts for issues:

agent.sandbox.create_alert(
    condition="cpu_usage > 90%",
    action="notify",
    channel="slack"
)

Cost Optimization

Right-Sizing

Choose appropriate sandbox size:

Start small - Upgrade if needed
Monitor usage - Check actual resource consumption
Auto-scale - Upgrade during peak times

Auto-Shutdown

Enable auto-shutdown for cost savings:

# Shutdown after 15 minutes idle
agent.configure_sandbox(
    auto_shutdown=True,
    shutdown_after="15m"
)

Savings Example:

Without auto-shutdown: $0.10/hour × 24 hours = $2.40/day
With auto-shutdown (8 hours active): $0.10/hour × 8 hours = $0.80/day
Savings: 67%

Snapshot Management

Manage snapshot retention:

# Keep snapshots for 7 days
agent.configure_snapshots(
    retention="7d",
    max_snapshots=100
)

Troubleshooting

Sandbox Won’t Start

Symptoms: Sandbox stuck in “starting” state

Solutions:

Check resource limits
Verify image availability
Check network connectivity
Contact support if persists

Out of Disk Space

Symptoms: “No space left on device” errors

Solutions:

# Check disk usage
$ df -h

# Clean up old files
$ rm -rf /home/agent/output/old/*

# Or upgrade sandbox size
agent.configure_sandbox(disk_limit="50 GB")

Slow Performance

Symptoms: Commands take longer than expected

Solutions:

Check resource usage: agent.sandbox.metrics()
Upgrade sandbox size if needed
Optimize your code
Check network latency

Best Practices

Do’s ✅

Use auto-shutdown to save costs
Create manual snapshots before risky operations
Monitor resource usage regularly
Keep filesystem organized
Use environment variables for secrets
Clean up old files periodically

Don’ts ❌

Don’t store secrets in code
Don’t run untrusted code
Don’t ignore resource limits
Don’t skip snapshots before major changes
Don’t leave sandboxes running idle

Comparison with Competitors

Feature	Auteryn	Devin	Replit	Others
Persistence	✅ Full	⚠️ Limited	⚠️ Limited	❌ None
Auto-Snapshots	✅ Every 5 min	❌	❌	❌
Time-Travel	✅	⚠️ Manual	⚠️ Manual	❌
Auto-Shutdown	✅	❌	❌	❌
Shared Volumes	✅	❌	❌	❌
GPU Support	✅ Enterprise	✅	❌	❌

API Reference

Sandbox Management

# Start/stop
agent.sandbox.start()
agent.sandbox.stop()
agent.sandbox.restart()

# Status
status = agent.sandbox.status()

# Configuration
agent.configure_sandbox(
    size="medium",
    auto_shutdown=True,
    shutdown_after="30m"
)

Snapshots

# Create
agent.create_snapshot("my-snapshot")

# List
snapshots = agent.list_snapshots()

# Restore
agent.restore_snapshot("snapshot-id")

# Delete
agent.delete_snapshot("snapshot-id")

Monitoring

# Metrics
metrics = agent.sandbox.metrics()

# Logs
logs = agent.sandbox.logs(tail=100)

# Alerts
agent.sandbox.create_alert(
    condition="cpu_usage > 90%",
    action="notify"
)

Learn More

Questions?

How long do sandboxes persist? Indefinitely, until you delete them.
What happens to snapshots when I delete a sandbox? Snapshots are deleted too (configurable).
Can I access the sandbox directly? Yes, via SSH (Enterprise) or web terminal.
Are sandboxes backed up? Yes, automatic snapshots serve as backups.
Can I migrate sandboxes between regions? Yes, via snapshot export/import.

View all FAQs →