Start, stop and snapshot an environment

Run the persistent machine behind a managed Project and keep a copy of it before risky work.

Before you start

The host must be prepared before the first start; read Prepare a host if the panel reports Preparation required. You also need access to the managed Project.

Start, stop and restart

1. Open Projects and find the managed Project.
2. Open the Actions menu on its card, the button with three dots.
3. Choose Start environment. The first start provisions the environment, which happens on demand and needs a verified root filesystem.
4. Choose Stop environment to interrupt commands and Project services; its files and installed packages are kept. Stopping asks for confirmation.
5. Choose Restart environment to stop and start it again.

The menu enables only the actions the environment's current state allows and keeps them disabled while an operation for that Project runs. The Environments tab of the Project's detail holds its settings and the snapshot list.

Check that an operation finished

Start, stop, snapshot and restore are durable requests. Each returns an operation that may still be running, so check its status before you assume it finished. Retrying an interrupted request with the same request ID does not queue it twice.

The background operations dock follows only operations you started yourself in the web UI, including Project creation and selecting a stopped environment. Project deletion is tracked separately by Chetty's Project deletion operation.

• Administrators follow only their own operations too.
• Agent requests, API-token requests, automatic recovery and host preparation do not appear in the dock.
• A running operation survives a page reload, and a completed outcome stays until you acknowledge it.
• Each environment keeps its newest 20 operations; older settled ones are removed, and dismissing an outcome removes it across your tabs and devices.

Read the logs

The environment keeps a lifecycle log and a system journal that records what happens inside it. Logs return at most 1,000 lines, and Chetty reads the last 100 lines unless it asks for more. System logs in newly created containers are capped at 100 MB by default.

Take a snapshot

A complete snapshot captures the root filesystem, HOME, worktrees and data while execution is paused. A Project snapshot includes every component of its environment. A snapshot can carry a note of up to 2,000 characters; the web UI creates one without a note field, so a note comes only from a direct environment action call, and the list shows it when it is set.

Warning: Snapshots are crash-consistent, not database-consistent. Export application databases separately when you need them consistent.

1. Open the Actions menu on the managed Project's card in Projects.
2. Choose Create snapshot and confirm the warning.
3. Read the Complete snapshots list on the Project's Environments tab: every snapshot is listed newest first, with its time, the space it occupies, the base image it was taken from and its note when it has one.

Restore or delete a snapshot

1. Open the managed Project's Environments tab and find Complete snapshots.
2. Select Restore or Delete snapshot.
3. Confirm the action and read what it affects.

Restore replaces the environment with the selected snapshot in a fresh generation. It discards changes made after that snapshot and interrupts running work, so it asks for explicit confirmation.

Deleting a snapshot removes its stored copy from the host, and it is refused while another environment operation is pending or running, so a restore never loses the snapshot it is copying.

Delete a Project

Deleting a Project also deletes its environment and retained snapshots. The confirmation lists the affected storage paths, and Chetty removes dependent services, including published Sites, before deleting environment storage.

Note: If a service or storage owner cannot finish, deletion stays blocked with its reason and the Project is not reported as deleted. Retrying continues the saved cleanup instead of starting a second deletion.

Environments and snapshots left from the removed Podman runtime cannot be started or restored. They can be deleted individually or with their Project; delete the Project and create it again to get a working environment.

Files inside the environment

Reading and writing files reuses a connection inside the Project's environment, and access is checked for every operation.

• Stopping or restarting the environment, taking a snapshot, or revoking the connection owner's access closes that connection. The next authorized file operation opens a new one.
• A file operation that exceeds two minutes fails without being repeated automatically; ask for it again if you still need it.
• Files being uploaded, written or copied are hidden from listings and walks while the operation runs. Other dotfiles stay visible.

If something does not work

• The first start is refused: a host requirement is missing. Read Prepare a host and the requirement named in the refusal.
• The environment stopped itself: disk usage passed the Project's ceiling. Free space or raise the ceiling, then start it again.
• A snapshot cannot be deleted: another environment operation is pending or running. Wait for it to finish.
• An operation looks finished but nothing changed: open the operation and read its final status.

Related guides

Continue with Set environment limits and networking, Use the shared Project desktop, Share work in a Project worktree or Projects overview.