Publish and export changes

Automatic publication

Calling exec_command without workspace_session_id creates an automatic session with publish_then_destroy finalization. After its last command reaches terminal state, the runtime captures its filesystem delta, attempts publication, and destroys the session.

sandbox-runtime-cli --sandbox-id eos-abc exec_command "printf 'ready\n' > status.txt"
sandbox-runtime-cli --sandbox-id eos-abc file_read --path status.txt

File writes and edits without a session also publish directly as one operation-attributed layer. Reads without a session always project the latest published snapshot.

Explicit sessions

Commands and file operations can target an existing workspace session by ID. Such a session keeps private changes across operations and does not use automatic finalization. Its lifecycle and teardown operations are internal coordination surfaces, so this documentation does not present them as public CLI or MCP commands.

Teardown of an explicitly managed session discards unpublished changes. An integrating surface must own the session lifecycle and decide when capture/publication is appropriate.

Capture and conflicts

Capture turns a private upper directory into a candidate delta. Publication resolves that delta against newer durable history and either adds one immutable layer or rejects the change set. It is not a last-writer-wins file copy.

When publication rejects, inspect the latest snapshot, rerun the work from a fresh base, and avoid exporting until the intended changes are present in the published LayerStack. The workspace coordination chapter explains the all-or-reject path.

Compact layer history

Squashing replaces every eligible published run with equivalent flattened layers and live-remounts active sessions onto compact chains. It preserves visible filesystem results; it is a maintenance operation, not publication.

sandbox-manager-cli squash_layerstacks --sandbox-id eos-abc
sandbox-observability-cli layerstack --sandbox-id eos-abc

Export to the host

export_changes folds every published layer above the base with newest-wins, whiteout-aware semantics. Directory format applies the delta to an absolute host destination; tar formats write an archive file.

sandbox-manager-cli export_changes --sandbox-id eos-abc --dest /absolute/path/to/destination
sandbox-manager-cli export_changes --sandbox-id eos-abc --dest /tmp/delta.tar --format tar
sandbox-manager-cli export_changes --sandbox-id eos-abc --dest /tmp/delta.tar.zst --format tar-zst

Internal export_layerstack and read_export_chunk requests are implementation details used by the manager operation. They are not public tools. Export only into a destination where applying the published delta is intended.