🍳 Overeasy - branching filesystem for agents and RL

Overeasy is a filesystem state manager for coding agents and RL rollouts. It uses an append-only log on S3 for durability, allowing you to pause-resume an agent/RL filesystem state across hosts, revert to previous states, and cheaply branch into parallel states.

The filesystem is served as a FUSE mount overlay over a base directory. Changes are copy-on-write, isolating mutations from your agent/rollout under a Session ID. Sessions can be paused, resumed, branched, and reverted to any prior state using the Overeasy CLI.

Quickstart

The intended way to use Overeasy is in Modal Sandboxes (though it'd work on any Linux machine!)

See here for a working example of Overeasy running as the filesystem durability layer in a Modal Sandbox environment.

Installation

curl -sSL https://raw.githubusercontent.com/modal-labs/overeasy/main/install.sh | bash

This will install the overeasy CLI (aliased to oe) into your machine.

Environment Setup

Overeasy uses S3 and S2 keys as dependencies. These keys will be provided to you by the Modal team (ask for Erik D or Raymond).

Example Usage:

Create a new session

oe session new 
# -> <new_session_id>

Create a new session relative to the current directory.

[!NOTE] Each session is a diff relative to a stable "lower" directory, so the session becomes invalid if the lower directory changes outside of a session mount. The lower may be specified using --lower, defaulting to the current working directory.

Serve a session as a mounted overlay

oe mount <session_id>

Mount over the current directory and serve the state for <session_id>.

For a newly created session, the mounted view will show the unmodified lower directory. Modifications to the file contents while the server is running will be isolated to the session.

To unmount, ctrl+c. This will make the current directory return to its unmodified state.

[!IMPORTANT] A session should only ever be served by one host at a time.

Resume a session

oe mount <session_id>

Mounting over the current directory with a session ID will resume from the latest state.

List sessions

oe session ls

List sessions known to this host. Sessions started on other hosts may not be listed, but will be discovered when used in a mount.

Branch from the current state

oe session branch <session_id>
# -> <new_session_id>

Branch from the tail of the specified session, creating a new session ID.

The original session remains valid, and may be resumed from.

Revert to a previous state

oe session branch <session_id> --to <timestamp>
# -> <new_session_id>

Revert back to a previous state of the specified session using the --to flag in a branch commmand.

Session logs are append-only, so reverts really are just new branches starting from a previous state. The original session remains valid.