Virtual filesystem

The virtual filesystem (VFS) gives simse a controlled interface for file operations. Instead of reading and writing the host filesystem directly, all file I/O goes through the VFS layer, which logs every operation, enforces path constraints, and optionally keeps a full history of every change.

Two modes

The VFS supports two modes, selected by URI scheme in your configuration.

In-memory (vfs://)

The in-memory filesystem keeps all files and directories in process memory. Nothing is written to disk. When the session ends, the filesystem is discarded.

Use vfs:// when:

• You want ephemeral scratch space with no disk I/O
• You are generating intermediate files that do not need to persist
• You need a clean, isolated environment with no access to host files
• You want the fastest possible file operations

Characteristics:

• No persistence — contents are gone when the session exits
• No host filesystem permissions apply — every path is writable
• Limited by available process memory
• Supports the full VFS API: read, write, append, list, stat, mkdir, remove

Disk-backed (file://)

The disk-backed filesystem reads from and writes to real files on the host. It adds a shadow history layer on top, which records every write operation for change tracking and rollback.

Use file:// when:

• You need file changes to persist beyond the session
• You are working with real project files
• You want shadow history for change tracking and rollback

Characteristics:

• Reads and writes real files at the specified root path
• Host filesystem permissions apply — simse must have appropriate access
• Shadow history tracks every write without altering original files

Shadow history

Shadow history is the disk-backed mode's most distinctive feature. Every write to a file:// path creates a shadow copy of the previous content before the write is applied. simse tracks file versions using content-addressed storage in a .simse/ directory. Each file version is stored by its SHA256 hash under objects/, and a per-file manifest under manifests/ records the version history with entries containing version number, hash, size, content type, and timestamp.

Shadow history enables:

• Viewing diffs — Compare any two shadow entries to see what changed
• Rollback — Restore the file to any previous shadow entry
• Audit — Know exactly what simse changed, when, and in what order

Shadow files are stored under a .simse/ directory in the filesystem root. They are not tracked by version control unless you explicitly add them — the shadow directory is added to .gitignore by default.

Shadow history does not apply to reads. Only write operations (write, append, truncate) create shadow entries.

Shadow history is not available when using the SSH backend for filesystem operations. File changes on remote hosts are not tracked.

Path model

The VFS enforces a root path constraint. All operations are relative to the configured root. Paths that escape the root (via .. traversal) are rejected with a permission error. This prevents simse from accidentally accessing or modifying files outside the project directory.

The root path is set per-session when simse launches. By default, simse uses the current working directory as the filesystem root. When running through the managed service or cloud, the root is set by the platform.

For the in-memory mode, the root is a virtual / with no host mapping.

Available operations

The VFS API covers standard filesystem operations:

Operation	Description
read(path)	Read file contents as bytes
write(path, bytes)	Write bytes to a file (creates if absent)
append(path, bytes)	Append bytes to an existing file
list(path)	List directory entries
stat(path)	Get metadata: size, modified time, type
mkdir(path)	Create a directory (recursive)
remove(path)	Delete a file or empty directory
rename(src, dst)	Rename or move a file
exists(path)	Check whether a path exists