|
| 1 | +# Ephemeral Jcode Cloud machines |
| 2 | + |
| 3 | +This is the infrastructure foundation for isolated benchmarks and other short-lived |
| 4 | +remote jobs. It does not implement a benchmark dashboard or automatically run a |
| 5 | +model. The backend implementation lives in the separate |
| 6 | +`solosystems-managed-cloud` repository. |
| 7 | + |
| 8 | +## Isolation and lifecycle |
| 9 | + |
| 10 | +`jcode cloud machine` still manages the account's persistent general-purpose host. |
| 11 | +`jcode cloud ephemeral` addresses a separate machine collection. It never uses |
| 12 | +`cloud move` or copies a live local session, its repository, or provider credentials. |
| 13 | +Each machine has its own SSH identity and pinned host-key file under |
| 14 | +`~/.jcode/cloud/ephemeral/<machine-id>/`. Native SSH attachment renders the actual |
| 15 | +Jcode TUI locally while the server and tools run remotely. No tmux is needed. |
| 16 | + |
| 17 | +Every create request has a hard lifetime of 300 through 86,400 seconds, defaulting |
| 18 | +to one hour. The lifetime includes provisioning, bootstrap and disconnected time. |
| 19 | +Closing the TUI does not end the job or extend its deadline. The backend is |
| 20 | +responsible for TTL enforcement, automatic deletion, resource limits, ownership |
| 21 | +checks, VM credential revocation and cloud resource cleanup. **All files on the |
| 22 | +machine are disposable. Export results before expiry or termination.** |
| 23 | + |
| 24 | +The initial backend uses an operator-controlled fixed CPU machine size and caps |
| 25 | +concurrent machines. Clients cannot request arbitrary GPU/instance sizes or |
| 26 | +unbounded lifetimes. These machines use Jcode Cloud resources, not Modal credits. |
| 27 | +Model requests remain subject to the chosen provider's billing and limits. |
| 28 | + |
| 29 | +## Deployment prerequisite |
| 30 | + |
| 31 | +The CLI requires the new `/v1/cloud/machines` API, its additive database migration, |
| 32 | +and the backend's ephemeral feature flag. CLI compilation or mocked tests do not |
| 33 | +prove the API is deployed. Follow `docs/CLOUD_MACHINES.md` in the backend repo and |
| 34 | +validate a short-lived canary before enabling it broadly. |
| 35 | + |
| 36 | +Keep the persistent machine stopped/unchanged during the canary. Record its state |
| 37 | +before and after. Do not claim production acceptance until a real machine has |
| 38 | +been created, reached SSH, run preflight commands, exported its results, and been |
| 39 | +verified terminated, including the automatic-expiry case. |
| 40 | + |
| 41 | +## CLI |
| 42 | + |
| 43 | +```sh |
| 44 | +# Create returns promptly. Provisioning continues separately. |
| 45 | +jcode cloud ephemeral create --name bench-pilot --ttl-seconds 1800 --json |
| 46 | + |
| 47 | +# Inspect without waking the persistent machine. |
| 48 | +jcode cloud ephemeral list --json |
| 49 | +jcode cloud ephemeral status cm_0123456789abcdef0123456789abcdef --json |
| 50 | + |
| 51 | +# Execute commands, preserving stdin and stdout for upload/download pipelines. |
| 52 | +jcode cloud ephemeral exec cm_0123456789abcdef0123456789abcdef -- uname -m |
| 53 | + |
| 54 | +# Attach the real Jcode TUI. This waits for the new machine's SSH readiness. |
| 55 | +jcode cloud ephemeral attach cm_0123456789abcdef0123456789abcdef |
| 56 | + |
| 57 | +# Irreversible: destroys this ephemeral machine and its disk. |
| 58 | +jcode cloud ephemeral terminate cm_0123456789abcdef0123456789abcdef --yes --json |
| 59 | +``` |
| 60 | + |
| 61 | +Replace the example ID with the ID returned by create. A create request prints its |
| 62 | +UUID to stderr *before* sending it. If the network fails, retry with the same |
| 63 | +`--request-id UUID` and identical settings to avoid creating a second machine. |
| 64 | +JSON results go to stdout. The request ID and progress go to stderr. |
| 65 | + |
| 66 | +## Pinning a benchmark configuration |
| 67 | + |
| 68 | +A machine's bootstrap Jcode version is not necessarily the version being tested. |
| 69 | +Do not update a shared daemon or assume the bootstrap build supports the current |
| 70 | +native SSH protocol. Upload the exact candidate binary and use a dedicated daemon |
| 71 | +socket. The following is a manual setup recipe, not an automatic benchmark run: |
| 72 | + |
| 73 | +```sh |
| 74 | +ID=cm_0123456789abcdef0123456789abcdef |
| 75 | +BIN=/absolute/path/to/the/linux-x86_64/jcode |
| 76 | + |
| 77 | +# Record this locally with the benchmark revision, compiler, task and model config. |
| 78 | +sha256sum "$BIN" |
| 79 | +jcode cloud ephemeral exec "$ID" -- bash -lc 'mkdir -p "$HOME/bench"' |
| 80 | +jcode cloud ephemeral exec "$ID" -- bash -lc \ |
| 81 | + 'cat > "$HOME/bench/jcode.tmp" && chmod 700 "$HOME/bench/jcode.tmp" && mv "$HOME/bench/jcode.tmp" "$HOME/bench/jcode"' < "$BIN" |
| 82 | +jcode cloud ephemeral exec "$ID" -- bash -lc \ |
| 83 | + 'sha256sum "$HOME/bench/jcode"; "$HOME/bench/jcode" --version; cc --version; valgrind --version' |
| 84 | + |
| 85 | +# Upload a pristine benchmark checkout, without local credentials/build products. |
| 86 | +git -C /path/to/jcode-bench archive HEAD | \ |
| 87 | + jcode cloud ephemeral exec "$ID" -- bash -lc \ |
| 88 | + 'mkdir -p "$HOME/bench/tasks-src" && tar xf - -C "$HOME/bench/tasks-src"' |
| 89 | +``` |
| 90 | + |
| 91 | +Before launching, compare the remote binary hash to the local hash. Check the |
| 92 | +candidate's `server stdio` protocol and shared-library compatibility. Record the |
| 93 | +resolved provider, model, reasoning settings, tool policy and concurrency. The |
| 94 | +SSH attachment deliberately does not override an already-running daemon's model |
| 95 | +or tool configuration: set those when starting the dedicated remote daemon. |
| 96 | + |
| 97 | +For example, with a supported candidate and a deliberately selected model: |
| 98 | + |
| 99 | +```sh |
| 100 | +jcode cloud ephemeral exec "$ID" -- bash -lc \ |
| 101 | + 'nohup "$HOME/bench/jcode" --no-update --no-selfdev --provider jcode --model MODEL --socket /run/user/1000/bench.sock serve > "$HOME/bench/server.log" 2>&1 < /dev/null &' |
| 102 | + |
| 103 | +jcode cloud ephemeral attach "$ID" \ |
| 104 | + --remote-binary /home/ec2-user/bench/jcode \ |
| 105 | + --server-socket /run/user/1000/bench.sock \ |
| 106 | + --workdir /home/ec2-user/bench/tasks-src/tasks/json-unescape |
| 107 | +``` |
| 108 | + |
| 109 | +Replace `MODEL` with the intended provider-supported model. Starting model work |
| 110 | +can consume provider credit. The dedicated socket prevents the bootstrap daemon |
| 111 | +from silently serving a different Jcode binary/configuration. Use one machine |
| 112 | +per run initially; separate machines per task provide stronger resource isolation |
| 113 | +when running tasks in parallel. |
| 114 | + |
| 115 | +Retrieve artifacts while the machine is alive, then terminate it explicitly: |
| 116 | + |
| 117 | +```sh |
| 118 | +jcode cloud ephemeral exec "$ID" -- bash -lc \ |
| 119 | + 'tar czf - -C "$HOME/bench" tasks-src server.log' > bench-artifacts.tar.gz |
| 120 | +jcode cloud ephemeral terminate "$ID" --yes |
| 121 | +``` |
| 122 | + |
| 123 | +Do not include provider credentials in exported archives. A later benchmark runner |
| 124 | +should automate manifests, score updates, artifact retrieval and cleanup while |
| 125 | +retaining these same lifecycle and isolation guarantees. |
0 commit comments