Waypoint

Mon, 01 Jun 2026 00:00:00 +0000

Fast checkpoint/restore for branchable terminal environments.

Waypoint, formerly Checkpoint-lite, is a lightweight checkpoint/restore system for stateful terminal-based workloads. It lets users and AI agents save a live execution session, explore alternative actions, and restore earlier states without rebuilding the environment or replaying the full command history.

The key motivation is that useful task state is not only stored in files. During a realistic terminal workflow, an agent may install dependencies, activate environments, export shell variables, launch background services, mutate temporary files, and accumulate in-memory process state. Waypoint captures this broader execution context, including filesystem changes, process memory, and persistent shell/session state, while avoiding the overhead of full virtual-machine snapshots.

Key features

Session-level checkpointing. Captures the live terminal environment, including filesystem deltas, process state, memory state, and shell/session context.
Fast branching and rollback. Allows users or agents to create named checkpoints, try alternative execution paths, and return to meaningful intermediate states.
Lightweight OS design. Combines OverlayFS-based filesystem tracking with CRIU-based process checkpointing, without relying on heavyweight container-image commits or VM snapshots.
Persistent terminal support. Treats the shell and PTY session as part of the branchable environment, preserving context that is usually lost when commands are run in fresh terminals.
Agent-ready interface. Can be used directly through the Waypoint CLI or as the fast local backend for StateFork, our abstraction for branchable agent environments.

Why it matters

Modern AI agents increasingly operate inside real computing environments rather than static prompts. In these settings, simple retry-from-scratch strategies waste work and often fail to preserve the intermediate state that made a branch point valuable. Waypoint makes it practical to branch from the middle of a task: after dependencies are installed, tests are warmed up, services are running, or a bug has been reproduced.

This enables exploration patterns that are difficult with conventional sandboxes: trying several fixes from the same prepared state, rolling back failed actions without rebuilding the environment, comparing alternative command trajectories, and preserving reproducible traces for evaluation.

Relationship to StateFork

Waypoint is the fast local checkpoint/restore backend used by StateFork. StateFork provides a common interface for building environments, executing commands, taking snapshots, restoring states, and cleaning up resources across different backends. Waypoint provides the specialized backend for efficient local terminal-session branching.

Challenges / creative solutions

The hardest part was not only capturing files and memory, but preserving the terminal session itself. Many agent workflows depend on shell-local context such as current directories, activated environments, exported variables, background jobs, and attached PTY state. Waypoint addresses this by combining filesystem delta tracking, process checkpointing, and custom terminal/session management into one coherent branchable execution environment.

Container | Alex XU

Waypoint