Skip to content

Commit 5ae0559

Browse files
committed
cloud: add isolated ephemeral machine lifecycle and native attach
1 parent 2818e5d commit 5ae0559

11 files changed

Lines changed: 808 additions & 14 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ tokio-tungstenite = { version = "0.24", default-features = false, features = ["c
151151
# Serialization
152152
serde = { version = "1", features = ["derive"] }
153153
serde_json = { version = "1", features = ["raw_value"] }
154+
uuid = { version = "1", features = ["v4"] }
154155
toml = "0.8"
155156

156157
# CLI

‎docs/cloud-ephemeral.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
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.

‎src/cli/args.rs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@ use clap::{Parser, Subcommand, ValueEnum};
22

33
use super::provider_init::ProviderChoice;
44

5+
mod cloud_ephemeral;
56
mod google;
67
mod mcp;
8+
pub(crate) use cloud_ephemeral::CloudEphemeralCommand;
79
#[allow(unused_imports)]
810
pub(crate) use google::{GoogleAccessTierArg, GoogleLoginArgs};
911
pub(crate) use mcp::McpCommand;
@@ -719,6 +721,11 @@ pub(crate) enum ServerCommand {
719721

720722
#[derive(Subcommand, Debug)]
721723
pub(crate) enum CloudCommand {
724+
/// Manage disposable remote machines with mandatory automatic expiry.
725+
Ephemeral {
726+
#[command(subcommand)]
727+
action: CloudEphemeralCommand,
728+
},
722729
/// Upload, list, verify, and view cloud-synced sessions
723730
Sessions {
724731
#[command(subcommand)]

‎src/cli/args/cloud_ephemeral.rs‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
use clap::Subcommand;
2+
3+
/// Disposable machines, separate from the account's persistent cloud host.
4+
#[derive(Subcommand, Debug)]
5+
pub(crate) enum CloudEphemeralCommand {
6+
/// Create an isolated machine that is automatically destroyed at its deadline.
7+
Create {
8+
/// Hard lifetime in seconds, including startup time (5 minutes to 24 hours).
9+
#[arg(long, default_value_t = 3600, value_parser = clap::value_parser!(u32).range(300..=86400))]
10+
ttl_seconds: u32,
11+
/// Reuse this UUID when retrying a create request after a network failure.
12+
#[arg(long)]
13+
request_id: Option<String>,
14+
/// Optional short label for the run (letters, digits, hyphen, underscore).
15+
#[arg(long)]
16+
name: Option<String>,
17+
#[arg(long)]
18+
json: bool,
19+
},
20+
/// List your ephemeral machines. Does not wake or create any machine.
21+
List {
22+
#[arg(long)]
23+
json: bool,
24+
},
25+
/// Inspect one ephemeral machine without authorizing SSH.
26+
Status {
27+
id: String,
28+
#[arg(long)]
29+
json: bool,
30+
},
31+
/// Irreversibly destroy an ephemeral machine and its disk.
32+
Terminate {
33+
id: String,
34+
/// Explicitly acknowledge destruction of this machine's files.
35+
#[arg(long, required = true)]
36+
yes: bool,
37+
#[arg(long)]
38+
json: bool,
39+
},
40+
/// Attach the real local Jcode TUI to the remote machine, without tmux.
41+
Attach {
42+
id: String,
43+
/// Exact remote Jcode binary to use.
44+
#[arg(long, default_value = "/opt/jcode-cloud/jcode")]
45+
remote_binary: String,
46+
#[arg(long)]
47+
workdir: Option<String>,
48+
#[arg(long)]
49+
server_socket: Option<String>,
50+
#[arg(long)]
51+
session: Option<String>,
52+
},
53+
/// Run a command remotely. stdin/stdout are preserved for scripts and uploads.
54+
Exec {
55+
id: String,
56+
#[arg(last = true, required = true, num_args = 1..)]
57+
command: Vec<String>,
58+
},
59+
/// Internal SSH ProxyCommand for one ephemeral machine.
60+
#[command(hide = true)]
61+
Proxy { id: String },
62+
}
63+
64+
#[cfg(test)]
65+
mod tests {
66+
use crate::cli::args::{Args, CloudCommand, CloudEphemeralCommand, Command};
67+
use clap::Parser;
68+
69+
#[test]
70+
fn ephemeral_cli_enforces_ttl_and_destructive_confirmation() {
71+
let args = Args::try_parse_from([
72+
"jcode",
73+
"cloud",
74+
"ephemeral",
75+
"create",
76+
"--ttl-seconds",
77+
"600",
78+
"--name",
79+
"bench-1",
80+
"--json",
81+
])
82+
.unwrap();
83+
assert!(matches!(
84+
args.command,
85+
Some(Command::Cloud(CloudCommand::Ephemeral {
86+
action: CloudEphemeralCommand::Create {
87+
ttl_seconds: 600,
88+
json: true,
89+
..
90+
}
91+
}))
92+
));
93+
for args in [
94+
vec![
95+
"jcode",
96+
"cloud",
97+
"ephemeral",
98+
"create",
99+
"--ttl-seconds",
100+
"299",
101+
],
102+
vec![
103+
"jcode",
104+
"cloud",
105+
"ephemeral",
106+
"create",
107+
"--ttl-seconds",
108+
"86401",
109+
],
110+
vec![
111+
"jcode",
112+
"cloud",
113+
"ephemeral",
114+
"terminate",
115+
"cm_0123456789abcdef0123456789abcdef",
116+
],
117+
] {
118+
assert!(Args::try_parse_from(args).is_err());
119+
}
120+
Args::try_parse_from([
121+
"jcode",
122+
"cloud",
123+
"ephemeral",
124+
"terminate",
125+
"cm_0123456789abcdef0123456789abcdef",
126+
"--yes",
127+
])
128+
.unwrap();
129+
}
130+
131+
#[test]
132+
fn ephemeral_attach_and_exec_do_not_steal_global_flags() {
133+
let id = "cm_0123456789abcdef0123456789abcdef";
134+
let args = Args::try_parse_from([
135+
"jcode",
136+
"cloud",
137+
"ephemeral",
138+
"attach",
139+
id,
140+
"--workdir",
141+
"/home/ec2-user/bench",
142+
"--server-socket",
143+
"/run/user/1000/bench.sock",
144+
"--session",
145+
"test",
146+
"--remote-binary",
147+
"/opt/bench/jcode",
148+
])
149+
.unwrap();
150+
assert!(matches!(
151+
args.command,
152+
Some(Command::Cloud(CloudCommand::Ephemeral {
153+
action: CloudEphemeralCommand::Attach {
154+
workdir: Some(_),
155+
server_socket: Some(_),
156+
session: Some(_),
157+
..
158+
}
159+
}))
160+
));
161+
let args = Args::try_parse_from([
162+
"jcode",
163+
"cloud",
164+
"ephemeral",
165+
"exec",
166+
id,
167+
"--",
168+
"printf",
169+
"--help",
170+
])
171+
.unwrap();
172+
assert!(
173+
matches!(args.command, Some(Command::Cloud(CloudCommand::Ephemeral {
174+
action: CloudEphemeralCommand::Exec { command, .. }
175+
})) if command == ["printf", "--help"])
176+
);
177+
}
178+
}

0 commit comments

Comments
 (0)