GitHub - JaiCode08/teleport-env · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
JaiCode08
teleport-env
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>3 Commits<br>3 Commits
logs
logs
teleport_env
teleport_env
tests
tests
.gitignore
.gitignore
Dockerfile.testbed
Dockerfile.testbed
LICENSE
LICENSE
README.md
README.md
run_benchmarks.sh
run_benchmarks.sh
setup.sh
setup.sh
View all files
Repository files navigation
Teleport-Env
An ultra-fast, OS-level snapshot and rollback sandbox designed for autonomous coding agents, Monte Carlo Tree Search (MCTS), and reinforcement learning.
1. The Problem
Coding agents need environments to test generated bash commands and scripts. However, standard Docker containers take 3 to 5 seconds to restart when an agent inevitably destroys the filesystem or corrupts a background process. This high latency makes it impossible to run high-throughput MCTS search loops or deep reinforcement learning across thousands of branches.
2. Inspiration
Teleport-Env is directly inspired by DeltaBox ("DeltaBox: A Fast File-System Rollback Facility for Destructive Agentic Testing"). DeltaBox proposed a sub-millisecond rollback mechanism using a customized kernel module. We bring that exact architecture to standard Linux distributions entirely in userspace using overlayfs and CRIU.
3. How it Works
We utilize a Cold Layer Switch architecture to bypass naive file copying completely:
The Sandbox (OverlayFS) : The agent's workspace runs inside an overlayfs mount with a read-only lowerdir and a volatile upperdir.
The Checkpoint (CRIU) : When taking a snapshot, we use Checkpoint/Restore In Userspace (CRIU) to dump the exact memory state, file descriptors, and PID tree of the running Python application into a binary image, while rotating the upperdir into the read-only stack.
The Rollback : If an agent corrupts the environment, we instantly SIGKILL the process, wipe the volatile upperdir, and inject the CRIU memory image back into the kernel. The application resumes from the exact millisecond the snapshot was taken, with a pristine filesystem.
(Note: Because CRIU requires specific kernel capabilities like CONFIG_CHECKPOINT_RESTORE, teleport-env uses Canonical Multipass to run on a native Ubuntu kernel, bypassing Windows WSL2 limitations).
4. Project Structure
teleport-env/<br>├── teleport_env/ # Core library<br>│ └── core.py # TeleportSandbox & CRIU/OverlayFS orchestrator<br>├── tests/ # Testing Suite<br>│ ├── counter_server.py # Background Python app for memory snapshots<br>│ ├── test_benchmark.py # Destructive rollback latency benchmark<br>│ └── test_mcts_agent.py # Autonomous OpenRouter + Qwen agent loop<br>├── logs/ # Automated testing output<br>├── setup.sh # Docker image build & Multipass container init<br>├── run_benchmarks.sh # Automated sandbox wipe & test runner<br>├── Dockerfile.testbed # Container configured with bleeding-edge CRIU<br>└── .env # Local environment keys (e.g. OPENROUTER_KEY)
5. Setup & Environment
Because CRIU requires advanced kernel capabilities (specifically CONFIG_CHECKPOINT_RESTORE and PTRACE_O_SUSPEND_SECCOMP), the execution environment dictates the setup process.
Native Linux (Ubuntu/Debian)
If you are running natively on a Linux host that supports these kernel features, you do not need virtualization. You can execute the testbed directly using Docker:
Clone the repository and configure your OpenRouter key:<br>.env">echo 'OPENROUTER_KEY="sk-or-v1-..."' > .env
Initialize the Docker sandbox and build the CRIU binaries:<br>sudo bash setup.sh
Run the benchmarking and MCTS test suites:<br>sudo bash run_benchmarks.sh
Windows / macOS (Virtualization Required)
Standard Windows WSL2 and Docker Desktop environments will fail because they strip the necessary CRIU kernel capabilities. To bypass this, teleport-env must be tested within a native Ubuntu environment using Canonical Multipass .
Install Multipass:<br># Windows<br>winget install Canonical.Multipass
# macOS<br>brew install...