remo-cli 1.0.3__tar.gz → 2.0.0__tar.gz

{remo_cli-1.0.3 → remo_cli-2.0.0}/.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
     "name": "Python Agentic Development",
-    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
     "remoteUser": "vscode",
     "features": {
         "ghcr.io/devcontainers/features/python:1": {},
@@ -40,7 +40,9 @@
         "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind,consistency=cached",
         "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached",
 	"source=${localEnv:HOME}/.aws,target=/home/vscode/.aws,type=bind,consistency=cached",
-        "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached"
+        "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached",
+        "source=${localWorkspaceFolder}/../site,target=/workspaces/site,type=bind,consistency=cached",
+        "source=${localWorkspaceFolder}/../remo-broker,target=/workspaces/remo-broker,type=bind,consistency=cached"
     ],
     "postCreateCommand": "python3 --version && node --version"
 }

{remo_cli-1.0.3 → remo_cli-2.0.0}/.github/workflows/smoke-test.yml

@@ -139,9 +139,55 @@ jobs:
           echo "$OUT" | grep -q "EBS volume:"  || { echo "FAIL: missing EBS volume"; exit 1; }
           echo "aws info: PASS"
 
+      - name: Snapshot — create (async kickoff)
+        run: |
+          SNAP=ci-smoke-aws
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(uv run remo aws snapshot create "$INSTANCE_NAME" --name "$SNAP" --description "smoke test")
+          echo "$OUT"
+          echo "$OUT" | grep -q "creation started" || { echo "FAIL: missing async-create hint"; exit 1; }
+          echo "$OUT" | grep -q "several minutes" || { echo "FAIL: missing duration hint"; exit 1; }
+          echo "aws snapshot create: PASS"
+
+      - name: Snapshot — list shows pending then available
+        run: |
+          # Initial list: pending (or already available if AWS is fast today)
+          uv run remo aws snapshot list "$INSTANCE_NAME" | tee /tmp/list-1.txt
+          grep -q "$SNAP_NAME" /tmp/list-1.txt || { echo "FAIL: snapshot missing from initial list"; exit 1; }
+          grep -q "STATUS" /tmp/list-1.txt || { echo "FAIL: AWS list missing STATUS column"; exit 1; }
+
+          # Poll up to 10 minutes for the snapshot to reach available state
+          for attempt in $(seq 1 60); do
+            OUT=$(uv run remo aws snapshot list "$INSTANCE_NAME")
+            if echo "$OUT" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" >/dev/null; then
+              echo "Snapshot $SNAP_NAME is available (attempt $attempt)"
+              break
+            fi
+            echo "Attempt $attempt: not yet available; sleeping 10s..."
+            sleep 10
+          done
+          uv run remo aws snapshot list "$INSTANCE_NAME" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" \
+            || { echo "FAIL: snapshot did not reach available within 10 min"; exit 1; }
+          echo "aws snapshot list: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          uv run remo aws snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes
+          # Verify it's gone from list
+          OUT=$(uv run remo aws snapshot list "$INSTANCE_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"; exit 1
+          fi
+          echo "aws snapshot delete: PASS"
+
       - name: Teardown
         if: always()
         run: |
+          # Best-effort cleanup of any leftover smoke snapshots (in case of
+          # mid-step failure) before tearing down the instance.
+          if [ -n "${SNAP_NAME:-}" ]; then
+            uv run remo aws snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes 2>/dev/null || true
+          fi
           uv run remo aws destroy --name "$INSTANCE_NAME" --yes --remove-storage || true
 
   # ===========================================================================
@@ -217,9 +263,51 @@ jobs:
           echo "$OUT" | grep -q "Volume:"      || { echo "FAIL: missing Volume"; exit 1; }
           echo "hetzner info: PASS"
 
+      - name: Snapshot — create (async kickoff)
+        run: |
+          SNAP=ci-smoke-hetzner
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(uv run remo hetzner snapshot create "$INSTANCE_NAME" --name "$SNAP" --description "smoke test")
+          echo "$OUT"
+          echo "$OUT" | grep -q "creation started" || { echo "FAIL: missing async-create hint"; exit 1; }
+          echo "$OUT" | grep -q "several minutes" || { echo "FAIL: missing duration hint"; exit 1; }
+          echo "hetzner snapshot create: PASS"
+
+      - name: Snapshot — list shows pending then available
+        run: |
+          uv run remo hetzner snapshot list "$INSTANCE_NAME" | tee /tmp/list-1.txt
+          grep -q "$SNAP_NAME" /tmp/list-1.txt || { echo "FAIL: snapshot missing from initial list"; exit 1; }
+          grep -q "STATUS" /tmp/list-1.txt || { echo "FAIL: Hetzner list missing STATUS column"; exit 1; }
+
+          # Poll up to 5 minutes for the snapshot to become available
+          for attempt in $(seq 1 30); do
+            OUT=$(uv run remo hetzner snapshot list "$INSTANCE_NAME")
+            if echo "$OUT" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" >/dev/null; then
+              echo "Snapshot $SNAP_NAME is available (attempt $attempt)"
+              break
+            fi
+            echo "Attempt $attempt: not yet available; sleeping 10s..."
+            sleep 10
+          done
+          uv run remo hetzner snapshot list "$INSTANCE_NAME" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" \
+            || { echo "FAIL: snapshot did not reach available within 5 min"; exit 1; }
+          echo "hetzner snapshot list: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          uv run remo hetzner snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes
+          OUT=$(uv run remo hetzner snapshot list "$INSTANCE_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"; exit 1
+          fi
+          echo "hetzner snapshot delete: PASS"
+
       - name: Teardown
         if: always()
         run: |
+          if [ -n "${SNAP_NAME:-}" ]; then
+            uv run remo hetzner snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes 2>/dev/null || true
+          fi
           uv run remo hetzner destroy --name "$INSTANCE_NAME" --yes --remove-volume || true
 
   # ===========================================================================
@@ -365,6 +453,93 @@ jobs:
           verify_tools
           echo "Post-update dev tools verification: PASS"
 
+      - name: Snapshot — create
+        run: |
+          SNAP=ci-smoke-incus
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name $SNAP --description 'smoke test'")
+          echo "$OUT"
+          echo "$OUT" | grep -q "Created snapshot '$SNAP'" || { echo "FAIL: missing sync-create success message"; exit 1; }
+          echo "incus snapshot create: PASS"
+
+      - name: Snapshot — list shows the new snapshot
+        run: |
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot list $CONTAINER_NAME")
+          echo "$OUT"
+          echo "$OUT" | grep -q "$SNAP_NAME" || { echo "FAIL: snapshot missing from list"; exit 1; }
+          # Incus list MUST NOT have a STATUS column (always AVAILABLE)
+          if echo "$OUT" | head -1 | grep -q "STATUS"; then
+            echo "FAIL: Incus list should not have a STATUS column"; exit 1
+          fi
+          echo "incus snapshot list: PASS"
+
+      - name: Snapshot — restore round-trip
+        run: |
+          SSH_CMD="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            -o ConnectTimeout=30 -o BatchMode=yes -i ~/.ssh/id_rsa remo@$HOST"
+
+          # Plant a marker file inside the container AFTER the snapshot was
+          # taken. If restore works, this marker must be gone afterwards.
+          $SSH_CMD "echo post-snapshot > /tmp/should-be-gone-after-restore.txt"
+          $SSH_CMD "test -f /tmp/should-be-gone-after-restore.txt"
+          echo "Marker file planted post-snapshot."
+
+          # Restore. -y to bypass the confirm. The provider stops the
+          # container, restores, and starts it again.
+          sg incus-admin -c "uv run remo incus snapshot restore $CONTAINER_NAME $SNAP_NAME -y"
+
+          # Container may take a few seconds to come back online after start.
+          for attempt in $(seq 1 12); do
+            if $SSH_CMD "echo connection-ok" 2>/dev/null | grep -q "connection-ok"; then
+              echo "SSH back after restore (attempt $attempt)"
+              break
+            fi
+            sleep 5
+          done
+
+          # The post-snapshot marker MUST be gone (SC-001).
+          if $SSH_CMD "test -f /tmp/should-be-gone-after-restore.txt" 2>/dev/null; then
+            echo "FAIL: marker file still present after restore — rollback didn't happen"
+            exit 1
+          fi
+          echo "Post-restore: marker file is gone — rollback PASS"
+          echo "incus snapshot restore: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          sg incus-admin -c "uv run remo incus snapshot delete $CONTAINER_NAME $SNAP_NAME -y"
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot list $CONTAINER_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"
+            echo "$OUT"
+            exit 1
+          fi
+          echo "incus snapshot delete: PASS"
+
+      - name: Snapshot — destroy-time cleanup prompt
+        run: |
+          # Create two snapshots, then destroy with -y. The destroy-time prompt
+          # is bypassed by -y, defaulting to KEEP snapshots (safer default).
+          # The destroy output must mention the snapshots and the keep-warning.
+          # We re-create the container after so the rest of the suite (cp tests)
+          # has a clean target.
+          sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name keep-1"
+          sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name keep-2"
+
+          # Capture destroy output to verify the prompt path fires
+          OUT=$(sg incus-admin -c "uv run remo incus destroy --name $CONTAINER_NAME --yes" 2>&1 || true)
+          echo "$OUT"
+          echo "$OUT" | grep -q "has 2 snapshot" || { echo "FAIL: destroy did not mention snapshots"; exit 1; }
+          echo "$OUT" | grep -q "keeping the 2 snapshot" || { echo "FAIL: destroy did not print --yes keep warning"; exit 1; }
+          echo "incus destroy snapshot-prompt: PASS"
+
+          # Re-create the container for downstream steps (cp tests etc.)
+          sg incus-admin -c "uv run remo incus create --name $CONTAINER_NAME"
+          # Refresh $HOST since the container was rebuilt
+          HOST=$(sudo incus list $CONTAINER_NAME --format=json | \
+            python3 -c "import sys,json; d=json.load(sys.stdin)[0]['state']['network']['eth0']['addresses']; print([a['address'] for a in d if a['family']=='inet'][0])")
+          echo "HOST=$HOST" >> "$GITHUB_ENV"
+
       - name: Prepare for remo cp tests
         run: |
           # Make container name resolvable (remo stores name, not IP, for Incus)
@@ -628,6 +803,51 @@ jobs:
           $SSH_CMD "pkill -f 'python3 -m http.server 9090'" 2>/dev/null || true
           $SSH_CMD "pkill -f 'python3 -m http.server 3000'" 2>/dev/null || true
 
+      - name: Test remo shell -p / --exec / --detach (project-launch passthrough)
+        run: |
+          SSH_CMD="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            -o ConnectTimeout=30 -o BatchMode=yes -i ~/.ssh/id_rsa remo@$HOST"
+
+          # Plant a project dir without a .devcontainer so we exercise the
+          # host-side branches of project-launch (no docker dance needed in CI).
+          $SSH_CMD "mkdir -p ~/projects/smoke-proj && \
+            echo 'placeholder' > ~/projects/smoke-proj/README"
+
+          # --- Foreground --exec on a no-devcontainer project (Case 4) ---
+          OUT=$(uv run remo shell -p smoke-proj --exec 'echo hello-$REMO_PROJECT-$REMO_INSTANCE && pwd' 2>&1)
+          echo "$OUT"
+          echo "$OUT" | grep -q "hello-smoke-proj-" || {
+            echo "FAIL: --exec did not run / env vars missing"; exit 1; }
+          echo "$OUT" | grep -q "/projects/smoke-proj" || {
+            echo "FAIL: --exec did not cd into project dir"; exit 1; }
+          echo "remo shell -p --exec (foreground): PASS"
+
+          # --- Detached --exec writes log file and returns immediately ---
+          DETACH_OUT=$(uv run remo shell -p smoke-proj --detach \
+            --exec 'sleep 1 && echo detached-marker-$REMO_PROJECT' 2>&1)
+          echo "$DETACH_OUT"
+          echo "$DETACH_OUT" | grep -q "Launched detached" || {
+            echo "FAIL: detach didn't print launched message"; exit 1; }
+          # Give the background command a moment to finish
+          sleep 3
+          LOG=$($SSH_CMD "cat ~/.local/state/remo/smoke-proj.log")
+          echo "log contents:"; echo "$LOG"
+          echo "$LOG" | grep -q "detached-marker-smoke-proj" || {
+            echo "FAIL: detached command did not run / log missing marker"; exit 1; }
+          echo "remo shell -p --detach --exec: PASS"
+
+          # --- Validation: --exec without -p exits 2 ---
+          if uv run remo shell --exec 'true' 2>/dev/null; then
+            echo "FAIL: --exec without -p should have errored"; exit 1
+          fi
+          echo "validation: --exec without -p errors as expected"
+
+          # --- Validation: --detach without --exec exits 2 ---
+          if uv run remo shell -p smoke-proj --detach 2>/dev/null; then
+            echo "FAIL: --detach without --exec should have errored"; exit 1
+          fi
+          echo "validation: --detach without --exec errors as expected"
+
       - name: Teardown
         if: always()
         run: |

{remo_cli-1.0.3 → remo_cli-2.0.0}/.gitignore

@@ -41,6 +41,9 @@ env/
 .vscode/
 *.sublime-*
 
+# macOS
+.DS_Store
+
 # Maverick workflow state (ignore everything except checkpoints)
 .maverick/*
 !.maverick/checkpoints/

{remo_cli-1.0.3 → remo_cli-2.0.0}/CLAUDE.md

@@ -11,6 +11,7 @@ See `.specify/memory/constitution.md` for project principles and non-negotiable
 - N/A (Incus storage pools already configured by 001-bootstrap-incus-host) (002-incus-container-support)
 - Python 3.11+ + Click (CLI framework), InquirerPy (interactive picker), boto3 (AWS, optional), hcloud (Hetzner, optional) (003-python-cli-rewrite)
 - Flat file (`~/.config/remo/known_hosts`, colon-delimited) (003-python-cli-rewrite)
+- Cross-provider snapshot model (`models/snapshot.py`) + shared helpers in `core/snapshot.py` (name generator, validator, table formatter, destroy-time cleanup hook). No new runtime deps. (005-provider-snapshots)
 
 - Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (for zypper module) (001-bootstrap-incus-host)
 
@@ -131,10 +132,10 @@ Provider SDKs (boto3, hcloud) are lazy-imported with clear error messages if mis
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- 005-provider-snapshots: Added cross-provider snapshot CLI (`remo <P> snapshot {create,list,restore,delete}`) + destroy-time cleanup hook across Incus / Proxmox / AWS / Hetzner.
 - 003-python-cli-rewrite: Added Python 3.11+ + Click (CLI framework), InquirerPy (interactive picker), boto3 (AWS, optional), hcloud (Hetzner, optional)
 - 002-incus-container-support: Added Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (existing), Incus CLI (local)
 
-- 001-bootstrap-incus-host: Added Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (for zypper module)
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

{remo_cli-1.0.3 → remo_cli-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 1.0.3
+Version: 2.0.0
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE
@@ -113,6 +113,42 @@ The `fzf`-powered menu shows your projects from `~/projects`:
 - **c**: Clone a new repository
 - **x**: Exit to shell
 
+### Jump Straight to a Project
+
+Skip the menu and land directly in a project (devcontainer auto-launches):
+
+```bash
+remo shell -p my-app
+```
+
+Run a one-shot command inside the project's devcontainer instead of opening
+a shell — quote the command as a single string:
+
+```bash
+remo shell -p my-app --exec 'pytest -x'
+remo shell -p my-app --exec 'claude --remote-control'
+```
+
+Fire-and-forget — kick off a command on the remote and exit SSH immediately:
+
+```bash
+remo shell -p my-app --detach --exec 'claude remote-control --name remo-rc'
+remo shell -p my-app --detach --exec './long-build.sh'
+```
+
+Detached output is captured to `~/.local/state/remo/<project>.log` on the
+remote, so you can tail it later (`remo shell -p my-app --exec 'tail -f
+~/.local/state/remo/my-app.log'`). The command's environment gets
+`REMO_INSTANCE` and `REMO_PROJECT` exported automatically — handy for
+deterministic naming, e.g.:
+
+```bash
+remo shell -p my-app --detach --exec \
+  'claude remote-control --name "remo-$REMO_INSTANCE-$REMO_PROJECT"'
+```
+
+Then on your phone, open claude.ai/code and pick the session by name.
+
 ### Port Forwarding
 
 Forward remote ports to your local machine during SSH sessions:
@@ -160,12 +196,43 @@ Every remo environment includes:
 
 ---
 
+## Snapshots
+
+Capture a point-in-time copy of an instance before a risky change, then roll
+back if it breaks. Available on every provider, with the same command surface:
+
+```bash
+remo <provider> snapshot create <instance> [--name NAME] [--description TEXT]
+remo <provider> snapshot list    [INSTANCE]
+remo <provider> snapshot restore <instance> <snapshot> [-y]
+remo <provider> snapshot delete  <instance> <snapshot> [-y]
+```
+
+`--name` defaults to `remo-YYYYMMDD-HHMMSS`. `-y` / `--yes` bypasses the
+confirm prompt on destructive operations.
+
+| Provider | Create | Restore | Notes |
+|---|---|---|---|
+| **Incus**   | seconds | in-place rollback (container stopped briefly) | Free; uses native `incus snapshot`. |
+| **Proxmox** | seconds | in-place rollback (container stopped briefly) | Free; requires snapshot-capable rootfs storage (ZFS, LVM-thin, Btrfs, Ceph, NFS, CIFS). `dir` storage is rejected pre-flight. |
+| **AWS**     | async — several minutes | in-place EBS volume swap; stops the instance, swaps the root volume, restarts. Typically 2-5 min downtime. | Costs $ per GB-month in EBS. Pre-restore root volume is preserved as a tagged orphan — delete it manually once you've verified the restore. |
+| **Hetzner** | async — several minutes | server rebuild from the snapshot image, in-place. Typically 1-2 min downtime. | Costs € per GB-month. |
+
+`remo` does not estimate storage cost — check your provider's billing console.
+
+The `destroy` command on each provider checks for existing snapshots first and
+offers to clean them up. Decline and the snapshots remain (you'll be warned
+they continue to incur storage costs on AWS/Hetzner).
+
 ## CLI Reference
 
 ```bash
 # Connect to environment
 remo shell                          # Auto-connect (or picker if multiple)
 remo shell my-env                   # Connect to a specific environment
+remo shell -p my-app                # Skip the menu, jump to ~/projects/my-app
+remo shell -p my-app --exec 'pytest -x'              # Run command in devcontainer
+remo shell -p my-app --detach --exec 'claude remote-control --name rc'  # Fire and exit
 remo shell -L 8080                  # Shell + forward remote :8080 to local :8080
 remo shell -L 9000:8080             # Shell + forward remote :8080 to local :9000
 remo shell -L 8080 -L 3000          # Shell + forward multiple ports
@@ -223,6 +290,15 @@ remo proxmox update --name <n> --volume-size 40 --cores 4 --memory 4096
 remo proxmox destroy --name <n> [--yes] [--purge]   # Destroy container
 remo proxmox bootstrap --host <node>  # Verify node + download LXC template
 
+# Snapshots (all four providers)
+remo <provider> snapshot create <instance>                       # Auto-named
+remo <provider> snapshot create <instance> --name pre-x --description "before upgrade"
+remo <provider> snapshot list                                    # All instances
+remo <provider> snapshot list <instance>                         # One instance
+remo <provider> snapshot restore <instance> <snap-name> [-y]     # In-place rollback
+remo <provider> snapshot delete <instance> <snap-name> [-y]      # Remove
+# `<provider> destroy` will list existing snapshots and offer to clean them up first.
+
 # Updates
 uv tool upgrade remo-cli            # Update CLI to latest version
 remo <platform> update              # Update dev tools on remote

{remo_cli-1.0.3 → remo_cli-2.0.0}/README.md

@@ -94,6 +94,42 @@ The `fzf`-powered menu shows your projects from `~/projects`:
 - **c**: Clone a new repository
 - **x**: Exit to shell
 
+### Jump Straight to a Project
+
+Skip the menu and land directly in a project (devcontainer auto-launches):
+
+```bash
+remo shell -p my-app
+```
+
+Run a one-shot command inside the project's devcontainer instead of opening
+a shell — quote the command as a single string:
+
+```bash
+remo shell -p my-app --exec 'pytest -x'
+remo shell -p my-app --exec 'claude --remote-control'
+```
+
+Fire-and-forget — kick off a command on the remote and exit SSH immediately:
+
+```bash
+remo shell -p my-app --detach --exec 'claude remote-control --name remo-rc'
+remo shell -p my-app --detach --exec './long-build.sh'
+```
+
+Detached output is captured to `~/.local/state/remo/<project>.log` on the
+remote, so you can tail it later (`remo shell -p my-app --exec 'tail -f
+~/.local/state/remo/my-app.log'`). The command's environment gets
+`REMO_INSTANCE` and `REMO_PROJECT` exported automatically — handy for
+deterministic naming, e.g.:
+
+```bash
+remo shell -p my-app --detach --exec \
+  'claude remote-control --name "remo-$REMO_INSTANCE-$REMO_PROJECT"'
+```
+
+Then on your phone, open claude.ai/code and pick the session by name.
+
 ### Port Forwarding
 
 Forward remote ports to your local machine during SSH sessions:
@@ -141,12 +177,43 @@ Every remo environment includes:
 
 ---
 
+## Snapshots
+
+Capture a point-in-time copy of an instance before a risky change, then roll
+back if it breaks. Available on every provider, with the same command surface:
+
+```bash
+remo <provider> snapshot create <instance> [--name NAME] [--description TEXT]
+remo <provider> snapshot list    [INSTANCE]
+remo <provider> snapshot restore <instance> <snapshot> [-y]
+remo <provider> snapshot delete  <instance> <snapshot> [-y]
+```
+
+`--name` defaults to `remo-YYYYMMDD-HHMMSS`. `-y` / `--yes` bypasses the
+confirm prompt on destructive operations.
+
+| Provider | Create | Restore | Notes |
+|---|---|---|---|
+| **Incus**   | seconds | in-place rollback (container stopped briefly) | Free; uses native `incus snapshot`. |
+| **Proxmox** | seconds | in-place rollback (container stopped briefly) | Free; requires snapshot-capable rootfs storage (ZFS, LVM-thin, Btrfs, Ceph, NFS, CIFS). `dir` storage is rejected pre-flight. |
+| **AWS**     | async — several minutes | in-place EBS volume swap; stops the instance, swaps the root volume, restarts. Typically 2-5 min downtime. | Costs $ per GB-month in EBS. Pre-restore root volume is preserved as a tagged orphan — delete it manually once you've verified the restore. |
+| **Hetzner** | async — several minutes | server rebuild from the snapshot image, in-place. Typically 1-2 min downtime. | Costs € per GB-month. |
+
+`remo` does not estimate storage cost — check your provider's billing console.
+
+The `destroy` command on each provider checks for existing snapshots first and
+offers to clean them up. Decline and the snapshots remain (you'll be warned
+they continue to incur storage costs on AWS/Hetzner).
+
 ## CLI Reference
 
 ```bash
 # Connect to environment
 remo shell                          # Auto-connect (or picker if multiple)
 remo shell my-env                   # Connect to a specific environment
+remo shell -p my-app                # Skip the menu, jump to ~/projects/my-app
+remo shell -p my-app --exec 'pytest -x'              # Run command in devcontainer
+remo shell -p my-app --detach --exec 'claude remote-control --name rc'  # Fire and exit
 remo shell -L 8080                  # Shell + forward remote :8080 to local :8080
 remo shell -L 9000:8080             # Shell + forward remote :8080 to local :9000
 remo shell -L 8080 -L 3000          # Shell + forward multiple ports
@@ -204,6 +271,15 @@ remo proxmox update --name <n> --volume-size 40 --cores 4 --memory 4096
 remo proxmox destroy --name <n> [--yes] [--purge]   # Destroy container
 remo proxmox bootstrap --host <node>  # Verify node + download LXC template
 
+# Snapshots (all four providers)
+remo <provider> snapshot create <instance>                       # Auto-named
+remo <provider> snapshot create <instance> --name pre-x --description "before upgrade"
+remo <provider> snapshot list                                    # All instances
+remo <provider> snapshot list <instance>                         # One instance
+remo <provider> snapshot restore <instance> <snap-name> [-y]     # In-place rollback
+remo <provider> snapshot delete <instance> <snap-name> [-y]      # Remove
+# `<provider> destroy` will list existing snapshots and offer to clean them up first.
+
 # Updates
 uv tool upgrade remo-cli            # Update CLI to latest version
 remo <platform> update              # Update dev tools on remote

{remo_cli-1.0.3 → remo_cli-2.0.0}/ansible/roles/user_setup/tasks/main.yml

@@ -330,13 +330,29 @@
               echo "Entering devcontainer (exit to return to host shell)..."
               echo ""
 
+              # If REMO_DEVCONTAINER_CMD is set (project-launch passthrough),
+              # run that command inside the devcontainer instead of dropping
+              # into the user's shell. Wrapped in `bash -lc` so the user's
+              # command gets variable expansion, pipes, &&, and PATH from
+              # the devcontainer's login profile.
+              if [[ -n "$REMO_DEVCONTAINER_CMD" ]]; then
+                  _bash_flags="-lc"
+                  _exec_cmd="$REMO_DEVCONTAINER_CMD"
+              else
+                  _bash_flags="-c"
+                  _exec_cmd='if command -v zsh &> /dev/null; then exec zsh; else exec bash; fi'
+              fi
+
               # Run devcontainer shell (not exec, so we can stop container after)
-              if ! devcontainer exec --workspace-folder "$_project_dir" /bin/bash -c \
-                  'if command -v zsh &> /dev/null; then exec zsh; else exec bash; fi'; then
+              if ! devcontainer exec --workspace-folder "$_project_dir" \
+                  env REMO_INSTANCE="${REMO_INSTANCE:-$(hostname)}" \
+                      REMO_PROJECT="$ZELLIJ_SESSION_NAME" \
+                  /bin/bash $_bash_flags "$_exec_cmd"; then
                   echo ""
                   echo "devcontainer exec failed. [Press any key to continue]"
                   read -n 1 -s -r
               fi
+              unset _exec_cmd _bash_flags
 
               # After exiting devcontainer, stop the container to free resources
               echo ""
@@ -393,6 +409,14 @@
     group: "{{ remo_user }}"
     mode: '0755'
 
+- name: Install project-launch script
+  ansible.builtin.template:
+    src: project-launch.sh.j2
+    dest: "/home/{{ remo_user }}/.local/bin/project-launch"
+    owner: "{{ remo_user }}"
+    group: "{{ remo_user }}"
+    mode: '0755'
+
 - name: Verify remo user exists
   ansible.builtin.command: id {{ remo_user }}
   register: user_setup_user_info