Skip to content

BOOTH_LIFECYCLE.md

Latest commit

 

History

History
253 lines (169 loc) · 6.08 KB

BOOTH_LIFECYCLE.md

File metadata and controls

253 lines (169 loc) · 6.08 KB

booth lifecycle

Pause your work, resume it tomorrow — your container picks up right where you left off.

By default, CodingBooth containers are removed when they exit. With --keep-alive, the container is preserved after exit so you can resume it later with all state intact.

./booth --keep-alive --name myproject
# ... work, then exit ...
./booth start myproject          # resume where you left off

Back to README

Table of Contents

Overview

CodingBooth provides a set of lifecycle commands for managing container state. These commands let you list running and stopped booths, resume stopped containers, restart running ones, and clean up when you are done.

All lifecycle features are built on top of Docker container management. CodingBooth labels every container it creates so lifecycle commands can reliably find and operate on the right containers.

Default vs Keep-Alive

Default (no keep-alive)

run → RUNNING → exit → REMOVED (automatic cleanup)

The container is created with --rm. Once it exits, everything inside (installed packages, modified files outside mounted volumes) is gone.

Keep-alive mode

run --keep-alive → RUNNING → exit → STOPPED (preserved)
                                       ↓
                                   start → RUNNING (resumed)
                                       ↓
                                   stop → STOPPED
                                       ↓
                                   remove → REMOVED

The container persists after exit. You can resume it, restart it, or explicitly remove it when done.

Enable keep-alive via CLI flag or config:

./booth --keep-alive

Or in .booth/config.toml:

keep-alive = true

Lifecycle Commands

list

Show all booth-managed containers.

./booth list              # all booths
./booth list --running    # only running
./booth list --stopped    # only stopped
./booth list --name-only  # just container names

Output includes: name, status, variant, port, code path, daemon, keep-alive, and creation time.

start

Resume a stopped booth container.

./booth start myproject           # by name
./booth start --code ~/projects   # by code path
./booth start --daemon myproject  # resume in background

Target resolution priority:

  1. --name <name>
  2. Positional argument
  3. --code <path>
  4. Default booth name from current directory

stop

Stop a running booth container.

./booth stop myproject              # graceful stop (10s timeout)
./booth stop --force myproject      # immediate kill
./booth stop --timeout 30 myproject # custom timeout

If the container was created without --keep-alive, stop also removes it automatically.

restart

Restart a running booth in-place (same container, same configuration).

./booth restart myproject
./booth restart --timeout 30 myproject

From inside the container: Use booth--restart to restart with full config re-processing (re-reads config.toml, Boothfile, rebuilds image if needed). This is different from booth restart on the host, which keeps the same container and configuration. See booth run — Shutdown & Restart.

remove

Explicitly delete a booth container.

./booth remove myproject                 # remove a stopped booth
./booth remove --force myproject         # force-remove even if running
./booth remove container1 container2     # remove multiple

prune

Batch-remove all stopped booth containers.

./booth prune        # prompts for confirmation
./booth prune --yes  # skip confirmation

Also cleans up orphaned sidecar containers (DinD, sandbox) whose parent no longer exists.

Common Workflows

Day-to-day development

# Day 1: Start a persistent booth
./booth --keep-alive --name myproject

# Work inside the container...
# Exit when done (Ctrl+D or exit)

# Day 2: Resume
./booth start myproject

# Day 3: Resume in the background (for web-based variants)
./booth start --daemon myproject

Check what's running

./booth list

Clean up old containers

# See what's stopped
./booth list --stopped

# Remove all stopped booths
./booth prune --yes

# Or remove a specific one
./booth remove myproject

Run a daemon booth for a web IDE

./booth --keep-alive --daemon --variant codeserver --name my-ide
# Access VS Code at http://localhost:10000

# Later, stop and resume
./booth stop my-ide
./booth start --daemon my-ide

Persistence Rules

When a container is resumed via start or restart, its configuration is unchanged. The following cannot be modified without removing and recreating the container:

  • Container name (--name)
  • UI port (--port)
  • Bind mounts (-v)
  • Port mappings (-p)

Home directory persistence

Use --persist-home to preserve /home/coder (IDE settings, shell history, app configs) across sessions via a Docker named volume. See Persist Home Directory for details.

To change these values, remove the container and run a new one:

./booth remove myproject
./booth --keep-alive --name myproject --port 9000

Container Snapshots

Stopped keep-alive containers can be saved and shared using standard Docker commands.

Save container state as a new image

docker commit <container-name> <image-name>:<tag>

Export/import container filesystem

# Export
docker export -o backup.tar <container-name>

# Import as a new image
cat backup.tar | docker import - my-image:restored

Save/load images

# Save image to file
docker save -o my-image.tar <image-name>:<tag>

# Load on another machine
docker load -i my-image.tar

See the Docker documentation for more options.