Skip to content
GurtOS docs

Workspaces and layers

A workspace is a folder of files that tasks work on, such as a git repository or a folder of receipts. GurtOS never lets a task write to it directly. Each task gets its own copy, and its changes become a layer. That is what makes undo exact.

Workspaces

Section titled “Workspaces”

Workspaces live in BOX_HOME/workspaces/<name>. The home workspace always exists and is the default. Apps make their own with box.workspace(name, fromDir), empty or as a copy of a folder. A name may use letters, digits, ., _ and -.

The files you put in a workspace are its base. Only root can reach the base directly, and no task ever writes to it.

Layers

Section titled “Layers”

GurtOS builds every copy with overlayfs, the Linux file system that stacks folders on top of each other:

  • The base is at the bottom.
  • Each done task's changes sit on top of it as a layer, newest on top.
  • A running task sees the base plus the layers that were done when it started. Its own changes go into a new, empty folder on top, its upper layer.

When a task finishes, its upper layer joins the stack. The workspace's view, in BOX_HOME/views/<name>, is a read-only overlay of the base and every done layer. The view is what "the workspace now" means.

A workspace as a stack of layers The base files sit at the bottom and are never written. Each finished task adds one layer on top, newest highest. Undo takes one layer out; the others stay. The view you see is the base plus every done layer. A running task works in its own copy: its own new layer on top of the layers that were done when it started. One workspace, newest layer on top Task C done Task B undone: taken out Task A done Base files never written Undo removes one layer. The others stay, and the base never changes. The workspace view base + A + C, read-only Task D, running its own layer on top of A + C + base only its user can open it joins the stack when done
A workspace's base files stay at the bottom, unwritten. Done tasks stack on top, newest first. Undo takes one layer out of the stack.

A deleted file is a layer entry too. overlayfs records it as a whiteout, a marker that hides the file below. So a task that deletes a file leaves the base untouched, and undoing that task brings the file back.

Undo

Section titled “Undo”

Undo takes one task's layer out of the stack and rebuilds the view. Nothing else changes:

  • The base files are never written, so there is nothing to restore.
  • Every other done task keeps its layer, so its changes stay.
  • If the task is still running or waiting, the core stops its processes first, and denies any approval it was waiting on.

Undo is POST /api/tasks/<id>/undo. The portal's Undo button and Time Machine both call it. The task's state becomes undone, which is final, and the log records when. It does not record who asked for the undo.

Time Machine showing three task layers stacked over the base files, with a preview of what comes back and what stays

Time Machine, from the portal's design. It shows one workspace's layers, newest first, and previews an undo before you confirm it. Names and times are examples.

What undo does not do

Section titled “What undo does not do”

Undo removes file changes. It cannot recall what a task already sent out of the box: a payment, an email, a message to an API. Those calls are in the log so you can follow up. Some apps reverse their own effects when a task is undone. For example, undoing a purchase from the shopping agent refunds its order. See undo a task.

Layers built on other layers

Section titled “Layers built on other layers”

A task that started after task A sees A's changes, and may change them again. If you later undo A, the later task's layer stays in the stack. Its changes to A's files still apply on top, but files only A created are gone. Read the diff before you undo a task that later tasks built on.

Why overlayfs

Section titled “Why overlayfs”

Other ways to undo an agent have gaps. Git only covers files in a repository, and only if the agent commits. Snapshots of the whole disk roll back every task at once. Copying the folder per task costs disk and time.

overlayfs is in the kernel, costs nothing until a task writes, and records each task's changes in its own folder. The diff of a task is a walk of that one folder. Undo is a remount.

Limits

Section titled “Limits”
  • Mount options cap the number of layers at about 60 per workspace. Squashing old layers into the base is not built yet.
  • The diff API shows at most 200,000 bytes of unified diff. The list of changed paths is always complete.
  • A failed task's changes stay in its own layer and never join the workspace. You can read them, but no later task sees them.

On the Personal edition

Section titled “On the Personal edition”
Section titled “Related”