Merge pull request #130 from smol-machines/binbin-fix-workspace-and-run-timeout

fix: agents.md updates, test updates for correctness, fix bug with workspace symlink

Author: BinSquare

AGENTS.md

@@ -33,6 +33,11 @@ smolvm machine create myvm --ssh-agent --net
 # Pack into portable executable
 smolvm pack create --image python:3.12-alpine -o ./my-python
 ./my-python run -- python3 -c "print('hello')"
+
+# Create machine from packed artifact (fast start, no pull)
+smolvm machine create my-vm --from ./my-python.smolmachine
+smolvm machine start --name my-vm
+smolvm machine exec --name my-vm -- pip install requests
 ```
 
 ## When to Use What
@@ -43,6 +48,7 @@ smolvm pack create --image python:3.12-alpine -o ./my-python
 | Interactive shell | `smolvm machine run --net -it --image IMAGE -- /bin/sh` |
 | Persistent dev environment | `machine create` → `machine start` → `machine exec` |
 | Ship software as a binary | `smolvm pack create --image IMAGE -o OUTPUT` |
+| Fast persistent machine from packed artifact | `machine create NAME --from FILE.smolmachine` |
 | Use git/ssh with private keys safely | Add `--ssh-agent` to run or create |
 | Minimal VM without image | `smolvm machine run -s Smolfile` (bare VM) |
 | Declarative VM config | Create a Smolfile, use `--smolfile`/`-s` flag |
@@ -52,7 +58,9 @@ smolvm pack create --image python:3.12-alpine -o ./my-python
 - **`machine run`** — ephemeral. All changes are discarded when the command exits.
 - **`machine exec`** — persistent. Filesystem changes (package installs, config edits) persist across exec sessions for the same machine, whether bare or image-based. Changes are stored in an overlay on the machine's storage disk.
 - **`machine stop` + `start`** — changes persist across restarts. The persistent overlay is remounted preserving previous changes.
-- **`pack run`** / **`pack exec`** — ephemeral. Each exec starts fresh from the packed image.
+- **`pack run`** — ephemeral. Each run starts fresh from the packed image.
+- **`pack start` + `exec`** — daemon mode. `/workspace` persists across exec sessions and stop/start. Container overlay resets per exec (package installs don't persist — use `/workspace` for durable data).
+- **`machine create --from .smolmachine`** — creates a persistent named machine from a packed artifact. Boots from pre-extracted layers (~250ms, no image pull). Full `machine exec` persistence — package installs, file writes all survive across exec and stop/start.
 
 ## CLI Structure
 
@@ -62,6 +70,7 @@ All commands use named flags (no positional args except `machine create NAME` an
 smolvm machine run --image IMAGE [-- COMMAND]     # ephemeral
 smolvm machine exec --name NAME [-- COMMAND]      # run in existing VM
 smolvm machine create NAME [OPTIONS]              # create persistent
+smolvm machine create NAME --from FILE.smolmachine  # from packed artifact
 smolvm machine start [--name NAME]                # start (default: "default")
 smolvm machine stop [--name NAME]                 # stop
 smolvm machine delete NAME [-f]                   # delete
@@ -232,9 +241,10 @@ through the container's overlay filesystem so both commands see the
 same files.
 
 **`/workspace` shared directory:** Every machine has a `/workspace`
-directory that is shared between the VM and the container. It persists
-across `exec` sessions and is a good default location for scripts,
-data, and results:
+directory — bare VMs, image-based VMs, and machines created from
+`.smolmachine` artifacts. It persists across `exec` sessions and
+across `stop`/`start` cycles. It's a good default location for
+scripts, data, and results:
 
 ```bash
 # Typical agent workflow: copy code in, execute, extract results
@@ -321,6 +331,15 @@ The packed binary runs as a normal executable:
 ./my-app stop                                # stop daemon
 ```
 
+Alternatively, create a named machine from the `.smolmachine` for full lifecycle management:
+```bash
+smolvm machine create my-vm --from my-app.smolmachine
+smolvm machine start --name my-vm            # ~250ms boot, no image pull
+smolvm machine exec --name my-vm -- pip install x   # fully persistent
+smolvm machine stop --name my-vm
+smolvm machine ls                            # shows my-vm
+```
+
 The `.smolmachine` manifest includes registry-oriented metadata:
 - `host_platform` — host OS+arch this machine runs on (e.g., `darwin/arm64`), distinct from `platform` which is the guest
 - `created` — RFC 3339 timestamp of when the machine was packed

crates/smolvm-agent/src/main.rs

@@ -168,6 +168,18 @@ fn main() {
     // before this point, ensure_storage_mounted() handles the mount on demand.
     ensure_storage_mounted();
 
+    // Create /workspace symlink for bare VMs. Image-based VMs get /workspace
+    // via a bind mount in the container spec, but bare VMs run directly in the
+    // VM rootfs where /workspace doesn't exist. The symlink makes /workspace
+    // available in both modes.
+    {
+        let workspace_link = std::path::Path::new("/workspace");
+        let workspace_target = std::path::Path::new("/storage/workspace");
+        if !workspace_link.exists() && workspace_target.exists() {
+            let _ = std::os::unix::fs::symlink(workspace_target, workspace_link);
+        }
+    }
+
     // Initialize packed layers support (if SMOLVM_PACKED_LAYERS env var is set)
     let t0 = uptime_ms();
     if let Some(packed_dir) = storage::get_packed_layers_dir() {

src/cli/machine.rs

@@ -665,7 +665,7 @@ impl RunCmd {
                     )?
                 } else {
                     let (exit_code, stdout, stderr) =
-                        client.vm_exec(command, env, params.workdir.clone(), None)?;
+                        client.vm_exec(command, env, params.workdir.clone(), self.timeout)?;
                     if !stdout.is_empty() {
                         print!("{}", stdout);
                     }

tests/test_machine.sh

@@ -963,6 +963,19 @@ test_machine_run_timeout() {
     [[ "$output" == *"timed out"* ]] || [[ "$output" == *"Killed"* ]] || [[ $? -ne 0 ]]
 }
 
+# Regression: /workspace must exist on bare VMs (not just image-based).
+test_bare_vm_workspace() {
+    ensure_machine_running
+    local output
+    output=$($SMOLVM machine exec -- ls -d /workspace 2>&1)
+    [[ "$output" == *"/workspace"* ]] || { echo "FAIL: /workspace missing on bare VM"; return 1; }
+
+    # Write and read back
+    $SMOLVM machine exec -- sh -c 'echo ws-bare > /workspace/bare.txt' 2>&1 || return 1
+    output=$($SMOLVM machine exec -- cat /workspace/bare.txt 2>&1)
+    [[ "$output" == *"ws-bare"* ]]
+}
+
 test_machine_run_pipeline() {
     local output
     output=$($SMOLVM machine run --net --image alpine:latest -- sh -c "echo 'hello world' | wc -w" 2>&1)
@@ -1085,6 +1098,7 @@ run_test "Machine run: volume readonly" test_machine_run_volume_readonly || true
 run_test "Machine run: workdir" test_machine_run_workdir || true
 run_test "Machine run: detached" test_machine_run_detached || true
 run_test "Machine run: timeout" test_machine_run_timeout || true
+run_test "Bare VM: /workspace exists" test_bare_vm_workspace || true
 run_test "Machine images" test_machine_images || true
 run_test "Machine prune --dry-run" test_machine_prune_dry_run || true