withruntime 0.12.0 → 0.16.0

package/dist/products/network-products.d.ts

@@ -8,7 +8,10 @@ export type DnsRecord = {
 export type Domain = {
     id: string;
     hostname: string;
-    sandboxId: string;
+    /** The sandbox it serves; null for an App's. */
+    sandboxId: string | null;
+    /** The App it serves, through every deploy and rollback; null for a sandbox's. */
+    appId?: string | null;
     port: number;
     /** pending until the TXT record proves the name is yours, then active. */
     state: "pending" | "active" | "released";
@@ -20,6 +23,13 @@ export type Domain = {
     verifiedAt: string | null;
     checkedAt: string | null;
     checkError: string | null;
+    /** An App's domain's certificate, issued before visitors arrive: point the
+     * name at the App once `ready` is true. Null for a sandbox's. */
+    certificate?: {
+        ready: boolean;
+        expiresAt: string | null;
+        issuers: string[];
+    } | null;
     createdAt: string;
 };
 export type CheckedDomain = Domain & {
@@ -97,12 +107,20 @@ export type TunnelPeerCreated = {
 /** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
 export declare function domains(t: Transport): {
     /** Claims the hostname and answers the DNS records to set. Calling it again
-     * with another sandbox or port points the name there. */
+     * with another sandbox or port points the name there. With `appId`, an App
+     * serves it: add the `_acme-challenge` CNAME too, and point the name at
+     * the App once `certificate.ready` is true. */
     add: (input: {
         hostname: string;
+    } & ({
         sandboxId: string;
         port: number;
-    }, options?: RequestOptions) => Promise<CheckedDomain>;
+        appId?: never;
+    } | {
+        appId: string;
+        sandboxId?: never;
+        port?: never;
+    }), options?: RequestOptions) => Promise<CheckedDomain>;
     /** Checks the TXT record now; the name goes live when it matches. */
     verify: (hostname: string, options?: RequestOptions) => Promise<CheckedDomain>;
     get: (hostname: string, options?: RequestOptions) => Promise<Domain>;

package/dist/products/network-products.js

@@ -5,7 +5,9 @@ const enc = encodeURIComponent;
 export function domains(t) {
     return {
         /** Claims the hostname and answers the DNS records to set. Calling it again
-         * with another sandbox or port points the name there. */
+         * with another sandbox or port points the name there. With `appId`, an App
+         * serves it: add the `_acme-challenge` CNAME too, and point the name at
+         * the App once `certificate.ready` is true. */
         add: (input, options) => t.json({ method: "POST", path: "/v1/domains", body: input, ...options }),
         /** Checks the TXT record now; the name goes live when it matches. */
         verify: (hostname, options) => t.json({

package/dist/products/observability.d.ts

@@ -35,7 +35,7 @@ export type SandboxMetrics = {
     latest: MetricPoint | null;
     points: MetricPoint[];
 };
-export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed";
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "volume.recovered" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed";
 /** An event as /v1/events lists it and a webhook delivers it. */
 export type RuntimeEvent = {
     id: string;
@@ -113,7 +113,7 @@ export type UsageExportRow = {
     name: string | null;
     kind: string;
     meter: string;
-    /** credit, the trial's hours, or the month's included usage. */
+    /** credit, the trial's hours, or the month's free usage. */
     fundedBy: "credit" | "trial" | "allowance";
     startsAt: string;
     endsAt: string;
@@ -128,12 +128,17 @@ export type UsageExportRow = {
     /** Exact JSON text, preserving integers beyond JavaScript's number range. */
     measurementsJson: string | null;
     evidence: "measured" | "partial" | "missing" | null;
+    /** The resource is deleted and every charge it will ever have settled
+     * before finalThrough. A volume's backups bill on until retention ends. */
+    final: boolean;
 };
 export type UsageExportPage = {
     since: string;
     until: string;
     data: UsageExportRow[];
     nextCursor: string | null;
+    /** No row with settledAt before this can still appear or change. */
+    finalThrough: string | null;
     /** Concatenate pages in order; only the first page includes the header. */
     csv: string;
 };

package/dist/products/previews.d.ts

@@ -9,9 +9,12 @@ export type Preview = {
     /** `https://<port>-<sandbox>.<preview domain>/`. A private preview also
      * needs the token. */
     url: string;
-    /** Private previews: a fresh signed token. Send it as the
-     * `x-runtime-preview-token` header. */
+    /** Private previews: a token signed for this answer. Send it as the
+     * `x-runtime-preview-token` header. Every create and read signs its own;
+     * one signed before keeps working until its own expiry or a rotate. */
     token: string | null;
+    /** When this answer's token stops working. Not stored on the preview: a
+     * later read signs another token and leaves this one as it is. */
     tokenExpiresAt: string | null;
     /** Private previews: a link that carries the token once, for a browser. */
     urlWithToken: string | null;
@@ -48,7 +51,7 @@ export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
     /** Shares `port`, or changes its visibility and embedOrigins if it is
      * shared already. */
     create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
-    /** Every shared port, each private one with a fresh token. */
+    /** Every shared port, each private one with a fresh token that lasts a day; tokens signed before keep their own expiry. */
     list: (options?: RequestOptions) => Promise<Preview[]>;
     /** One preview, with a fresh private token. `expiresAt` bounds its expiry
      * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */

package/dist/products/previews.js

@@ -10,7 +10,7 @@ export function sandboxPreviews(t, sandbox) {
         /** Shares `port`, or changes its visibility and embedOrigins if it is
          * shared already. */
         create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
-        /** Every shared port, each private one with a fresh token. */
+        /** Every shared port, each private one with a fresh token that lasts a day; tokens signed before keep their own expiry. */
         list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
         /** One preview, with a fresh private token. `expiresAt` bounds its expiry
          * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */

package/dist/products/resources.d.ts

@@ -0,0 +1,54 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** The five verbs every resource product shares (CLOUD.md section 4, "One
+ * shape for every interface"; packages/cloud/src/api/resource-product.ts),
+ * and following one to a state. A product builds its client on these and
+ * adds only its own verbs. */
+export type ResourceRecord = {
+    id: string;
+    state: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+};
+export type ResourceListQuery<S extends string = string> = {
+    name?: string;
+    /** Repeated key:value filters; all must match. */
+    label?: readonly string[];
+    /** Defaults to the product's live states. */
+    state?: readonly S[];
+    /** 1 to 100; defaults to 50. */
+    limit?: number;
+    cursor?: string;
+};
+export type ResourceGetOptions<S extends string = string> = RequestOptions & {
+    waitFor?: S;
+    /** Server wait, 1 to 60 seconds; defaults to 30. Check the returned state. */
+    timeoutSeconds?: number;
+};
+export type ResourceWaitOptions = RequestOptions & {
+    /** Whole wait, including retries; defaults to 300000 ms. 0 disables it. */
+    timeoutMs?: number;
+    /** Delay between reads; defaults to 250 ms. */
+    pollMs?: number;
+};
+export type ResourceDeleteOptions = ResourceWaitOptions & {
+    wait?: boolean;
+};
+export declare const enc: typeof encodeURIComponent;
+/** One deadline covers the write, retries and every read. A timed-out delete
+ * can be retried after a process restart with this same key. */
+export declare function following<T>(options: ResourceWaitOptions, work: (request: RequestOptions, pause: () => Promise<void>) => Promise<T>): Promise<T>;
+/** A resource product's client at `/v1/<path>`. A wait ends at its target
+ * or at any of `settled`, which answers with the resource's error. */
+export declare function resource<R extends ResourceRecord, C, U, S extends string = R["state"]>(t: Transport, path: string, settled: readonly S[]): {
+    base: string;
+    /** Defaults belong to the API, so the SDK does not override them. */
+    create: (input: C, options?: RequestOptions) => Promise<R>;
+    get: (id: string, options?: ResourceGetOptions<S>) => Promise<R>;
+    list: (query?: ResourceListQuery<S>, options?: RequestOptions) => Promise<Page<R>>;
+    update: (id: string, input: U, options?: RequestOptions) => Promise<R>;
+    wait: (id: string, target: S, options?: ResourceWaitOptions) => Promise<R>;
+    delete: (id: string, options?: ResourceDeleteOptions) => Promise<R>;
+};

package/dist/products/resources.js

@@ -0,0 +1,122 @@
+import { RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+import { pause } from "../wait.js";
+export const enc = encodeURIComponent;
+function invalid(field) {
+    return new RuntimeError({
+        code: "invalid_request",
+        status: 0,
+        message: `${field} must be a finite, nonnegative number.`,
+        hint: "Fix the option and call again; nothing was sent.",
+        details: { field },
+    });
+}
+/** One deadline covers the write, retries and every read. A timed-out delete
+ * can be retried after a process restart with this same key. */
+export async function following(options, work) {
+    const { pollMs = 250, timeoutMs = 300_000, signal, ...rest } = options;
+    if (!Number.isFinite(pollMs) || pollMs < 0)
+        throw invalid("pollMs");
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw invalid("timeoutMs");
+    const deadline = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    const timer = timeoutMs > 0 ? setTimeout(() => deadline.abort(), timeoutMs) : undefined;
+    const request = { ...rest, timeoutMs: 0, signal: combined };
+    const poll = () => pause(pollMs, combined);
+    try {
+        combined.throwIfAborted();
+        const result = await work(request, poll);
+        combined.throwIfAborted();
+        return result;
+    }
+    catch (cause) {
+        if (!combined.aborted) {
+            // A read failure still belongs to the write that started this wait.
+            // Keep its key so a caller can recover after losing the reply.
+            if (cause instanceof RuntimeError && rest.idempotencyKey && !cause.idempotencyKey)
+                throw new RuntimeError({
+                    message: cause.message,
+                    code: cause.code,
+                    status: cause.status,
+                    requestId: cause.requestId,
+                    hint: cause.hint,
+                    details: cause.details,
+                    retryAfterMs: cause.retryAfterMs,
+                    idempotencyKey: rest.idempotencyKey,
+                    cause,
+                });
+            throw cause;
+        }
+        throw new RuntimeError({
+            code: "timeout",
+            status: 0,
+            message: "Waiting was cancelled or reached its deadline; the resource may still change.",
+            hint: "Read the resource to resume waiting. Retry a write with the same idempotencyKey.",
+            ...(rest.idempotencyKey === undefined ? {} : { idempotencyKey: rest.idempotencyKey }),
+            cause,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A resource product's client at `/v1/<path>`. A wait ends at its target
+ * or at any of `settled`, which answers with the resource's error. */
+export function resource(t, path, settled) {
+    const base = `/v1/${path}`;
+    const get = (id, options = {}) => {
+        const { waitFor, timeoutSeconds, ...request } = options;
+        return t.json({
+            method: "GET",
+            path: `${base}/${enc(id)}`,
+            query: { waitFor, timeoutSeconds },
+            ...request,
+        });
+    };
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: base,
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    const follow = async (id, target, request, pause, initial) => {
+        let record = initial ?? (await get(id, request));
+        for (;;) {
+            if (record.state === target)
+                return record;
+            if (settled.includes(record.state))
+                throw new RuntimeError({
+                    code: record.error?.code ?? "unexpected_state",
+                    status: 0,
+                    message: record.error?.message ?? `Expected ${target}, but ${id} reached ${record.state}.`,
+                    hint: "Read the resource and inspect its error before starting another change.",
+                    details: { id, state: record.state, target, resource: record },
+                    ...(request.idempotencyKey === undefined
+                        ? {}
+                        : { idempotencyKey: request.idempotencyKey }),
+                });
+            await pause();
+            record = await get(id, request);
+        }
+    };
+    return {
+        base,
+        /** Defaults belong to the API, so the SDK does not override them. */
+        create: (input, options) => t.json({ method: "POST", path: base, body: input, ...options }),
+        get,
+        list,
+        update: (id, input, options) => t.json({ method: "POST", path: `${base}/${enc(id)}:update`, body: input, ...options }),
+        wait: (id, target, options = {}) => following(options, (request, pause) => follow(id, target, request, pause)),
+        delete: (id, options = {}) => {
+            const { wait = false, pollMs, ...request } = options;
+            const remove = (rest) => t.json({ method: "DELETE", path: `${base}/${enc(id)}`, ...rest });
+            if (!wait)
+                return remove(request);
+            return following({ ...request, pollMs, idempotencyKey: request.idempotencyKey ?? crypto.randomUUID() }, async (rest, pause) => follow(id, "deleted", rest, pause, await remove(rest)));
+        },
+    };
+}

package/dist/products/secrets.d.ts

@@ -9,6 +9,17 @@ export type SecretRule = {
     methods?: string[];
     paths: string[];
 };
+/** Which sandboxes get a secret: those whose labels hold every pair of any one
+ * selector in `labels` (including sandboxes created or labelled later), and
+ * those named in `sandboxes`. Any other sandbox of the organization sees no
+ * placeholder, and its requests never carry the value. Absent on a secret:
+ * every sandbox of the organization. */
+export type SecretScope = {
+    /** 1 to 8 selectors of 1 to 8 key/value pairs: `[{ role: "hub" }]`. */
+    labels?: Array<Record<string, string>>;
+    /** 1 to 100 sandbox ids of the organization. */
+    sandboxes?: string[];
+};
 /** A secret your sandboxes use without seeing it. Every sandbox of your
  * organization has an environment variable of the secret's name holding
  * `placeholder`; the egress proxy sets `header` on every HTTPS request to
@@ -22,6 +33,8 @@ export type Secret = {
     header?: string;
     format?: string;
     rules?: SecretRule[];
+    /** Absent: every sandbox of the organization. */
+    only?: SecretScope;
     placeholder: string;
     valueBytes: number;
     createdAt: string;
@@ -45,6 +58,10 @@ export type SetSecret = {
      * Absent: every request to the hosts; replacing a secret without rules
      * clears them. */
     rules?: SecretRule[];
+    /** Only these sandboxes get it. Absent when replacing a secret: the scope it
+     * has stays, so a new value never widens who gets it. `{}`: every sandbox of
+     * the organization again. */
+    only?: SecretScope;
     /** Also keep a copy for scheduled jobs, which a job puts into its run's
      * environment (`jobs.create({ secrets: [...] })`). Unlike the sandboxes'
      * copy, the jobs copy is yours rather than the account's, versioned, and can
@@ -98,6 +115,11 @@ export declare function secrets(t: Transport): {
             enforced: boolean;
         }>>;
     };
+    /** Changes which sandboxes get a secret, without its value: `{}` is every
+     * sandbox of the organization again. */
+    scope: (name: string, only: SecretScope, options?: RequestOptions) => Promise<Secret & {
+        enforced: boolean;
+    }>;
     /** The sandboxes' secrets: names, hosts and placeholders. Never values.
      * `all()` includes the jobs copies. */
     list: (options?: RequestOptions) => Promise<Secret[]>;

package/dist/products/secrets.js

@@ -153,6 +153,14 @@ export function secrets(t) {
          * at once store both; if only the first lands, `SecretPartlyStoredError`
          * says so and the same call again finishes it. */
         set,
+        /** Changes which sandboxes get a secret, without its value: `{}` is every
+         * sandbox of the organization again. */
+        scope: (name, only, options) => t.json({
+            method: "PUT",
+            path: `${path(name)}/sandboxes`,
+            body: only,
+            ...options,
+        }),
         /** The sandboxes' secrets: names, hosts and placeholders. Never values.
          * `all()` includes the jobs copies. */
         list,

package/dist/products/volumes.d.ts

@@ -90,6 +90,9 @@ export type VolumeBackup = {
      * the host never began; back it up again. */
     errorCode?: string | null;
     createdAt: string;
+    /** When its copy off the volume's server began; null while it waits its
+     * turn behind other copies there. */
+    copyStartedAt?: string | null;
     readyAt: string | null;
     expiresAt: string;
 };

package/dist/sandbox.d.ts

@@ -8,6 +8,10 @@ import type { StreamUploadSource } from "./file-source.js";
 import { Machine, type MachineProduct } from "./machine.js";
 /** Sandboxes, as a product of the machine engine (machine.ts). */
 export declare const SANDBOXES: MachineProduct;
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export declare const EXEC_EXIT_GRACE: {
+    ms: number;
+};
 /** A running (or stopped) sandbox. Every method is one API call or a short
  * sequence of them; `await using sbx = await Sandbox.create()` deletes it at
  * the end of the block, or stops it, keeping its disk, if created with

package/dist/sandbox.js

@@ -87,6 +87,8 @@ function commandBody(command, options) {
         ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     };
 }
+/** How long past its timeoutMs a streamed exec waits for an exit that never came. */
+export const EXEC_EXIT_GRACE = { ms: 120_000 };
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Sandbox extends Machine {
     #t;
@@ -147,8 +149,22 @@ export class Sandbox extends Machine {
             let exit;
             let processId;
             let dropped = false;
+            // A command with a time limit ends by it, the server killing it if need
+            // be; an exit that never comes after (a follow that resumes forever)
+            // ends the wait past the limit and EXEC_EXIT_GRACE.ms, as a timeout,
+            // its process named and sent SIGTERM. The hub's release train waited
+            // 29 min on a 10 min command (15 October 2026).
+            // A timer cleared when the call ends, so none outlives the exec.
+            const deadline = options.timeoutMs === undefined ? undefined : new AbortController();
+            const timer = deadline
+                ? setTimeout(() => deadline.abort(), options.timeoutMs + EXEC_EXIT_GRACE.ms)
+                : undefined;
+            timer?.unref?.();
+            const signal = deadline && options.signal
+                ? AbortSignal.any([options.signal, deadline.signal])
+                : (deadline?.signal ?? options.signal);
             try {
-                for await (const event of this.execStream(command, options)) {
+                for await (const event of this.execStream(command, { ...options, signal })) {
                     if (event.type === "start")
                         processId = event.processId;
                     else if (event.type === "stdout" || event.type === "stderr") {
@@ -162,7 +178,16 @@ export class Sandbox extends Machine {
                 }
             }
             catch (error) {
-                throw await this.#unfinished(error, processId, options.signal);
+                if (!deadline?.signal.aborted || options.signal?.aborted)
+                    throw await this.#unfinished(error, processId, signal);
+                if (processId)
+                    await new Process(this.#t, this.id, { id: processId })
+                        .kill("SIGTERM")
+                        .catch(() => { });
+                exit = { type: "exit", exitCode: null, timedOut: true };
+            }
+            finally {
+                clearTimeout(timer);
             }
             result = {
                 exitCode: exit?.exitCode ?? null,

package/dist/snapshots.d.ts

@@ -37,6 +37,10 @@ export type Snapshot = {
         durableAt: string | null;
         storedBytes: number | null;
     };
+    /** An opaque tag for the server it is kept on, like `pl_3f9a0c1b2d4e5f60`.
+     * The same tag as a sandbox of yours means the same server. Null before it
+     * is placed. Absent from older servers. */
+    placement?: string | null;
     error: string | null;
     createdAt: string;
     readyAt: string | null;

package/dist/ssh.d.ts

@@ -16,6 +16,41 @@ export declare function sshKey(env: NodeJS.ProcessEnv): Promise<{
 export declare function resolveSandbox(runtime: Runtime, target: string): Promise<Sandbox>;
 export declare function sshConfig(env: NodeJS.ProcessEnv): Promise<string>;
 export declare function sshCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
+/** The editors `runtime sandboxes code` opens: each one's command line program
+ * and the URL scheme its app registers. All three are VS Code underneath and
+ * name an SSH remote the same way, `ssh-remote+<host>`. */
+export declare const EDITORS: {
+    readonly vscode: {
+        readonly name: "VS Code";
+        readonly bin: "code";
+        readonly scheme: "vscode";
+    };
+    readonly cursor: {
+        readonly name: "Cursor";
+        readonly bin: "cursor";
+        readonly scheme: "cursor";
+    };
+    readonly windsurf: {
+        readonly name: "Windsurf";
+        readonly bin: "windsurf";
+        readonly scheme: "windsurf";
+    };
+};
+export type EditorName = keyof typeof EDITORS;
+/** What opens a sandbox's folder in an editor over the `*.runtime` ssh host:
+ * the editor's own program and its arguments, or, without the program on the
+ * PATH, the link its app answers. */
+export declare function editorLaunch(editor: EditorName, sandboxId: string, path: string): {
+    host: string;
+    bin: "code" | "cursor" | "windsurf";
+    args: string[];
+    link: string;
+};
+/** `runtime sandboxes code <id|name> [--editor cursor] [--path /workspace] [--print]`:
+ * a sandbox opened in VS Code, Cursor or Windsurf in one step. It makes sure
+ * the sandbox has an SSH server and this machine has the `*.runtime` ssh
+ * entry, then hands the editor the SSH remote. */
+export declare function editorCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
 /** `runtime sandboxes port-forward <id> 5432 8080:3000 ...` */
 export declare function portForwardCommand(argv: string[], out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
 export {};

package/dist/ssh.js

@@ -11,6 +11,9 @@ ${me} sandboxes ssh config [--install]          The ssh config for \`ssh <id|nam
                                       VS Code Remote-SSH and JetBrains Gateway; --install adds
                                       it to ~/.ssh/config
 ${me} sandboxes ssh proxy <id|name>[.runtime]   ProxyCommand mode: SSH on stdin and stdout
+${me} sandboxes code <id|name> [--editor vscode|cursor|windsurf] [--path /workspace] [--print]
+                                      Open it in your editor over SSH; installs the ssh config
+                                      above once. --print gives the link instead
 ${me} sandboxes port-forward <id|name> <port|local:remote>... [--address 127.0.0.1]
                                       Forward local ports to ports in the sandbox, until Ctrl-C
 
@@ -98,7 +101,7 @@ Host *.runtime
 async function installConfig(env) {
     const file = join(configDirectory(env), "ssh", "config");
     await writeFile(file, await sshConfig(env), { mode: 0o600 });
-    const sshDir = join(homedir(), ".ssh");
+    const sshDir = join(env.HOME || homedir(), ".ssh");
     await mkdir(sshDir, { recursive: true, mode: 0o700 });
     const main = join(sshDir, "config");
     const current = await readFile(main, "utf8").catch(() => "");
@@ -236,6 +239,95 @@ function usageError(message, me) {
         hint: `Run \`${me} sandboxes ssh help\`.`,
     });
 }
+/** The editors `runtime sandboxes code` opens: each one's command line program
+ * and the URL scheme its app registers. All three are VS Code underneath and
+ * name an SSH remote the same way, `ssh-remote+<host>`. */
+export const EDITORS = {
+    vscode: { name: "VS Code", bin: "code", scheme: "vscode" },
+    cursor: { name: "Cursor", bin: "cursor", scheme: "cursor" },
+    windsurf: { name: "Windsurf", bin: "windsurf", scheme: "windsurf" },
+};
+/** What opens a sandbox's folder in an editor over the `*.runtime` ssh host:
+ * the editor's own program and its arguments, or, without the program on the
+ * PATH, the link its app answers. */
+export function editorLaunch(editor, sandboxId, path) {
+    const { bin, scheme } = EDITORS[editor];
+    const remote = `ssh-remote+${sandboxId}.runtime`;
+    return {
+        host: `${sandboxId}.runtime`,
+        bin,
+        args: ["--remote", remote, path],
+        link: `${scheme}://vscode-remote/${remote}${path}`,
+    };
+}
+/** Runs a program, answering whether it started and exited 0; a program
+ * missing from the PATH is false, not an error. */
+function launched(bin, args, env) {
+    return new Promise((resolve) => {
+        const child = spawn(bin, args, {
+            env,
+            stdio: "ignore",
+            // `code` and `cursor` are .cmd scripts on Windows.
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => resolve(false));
+        child.on("exit", (code) => resolve(code === 0));
+    });
+}
+/** `runtime sandboxes code <id|name> [--editor cursor] [--path /workspace] [--print]`:
+ * a sandbox opened in VS Code, Cursor or Windsurf in one step. It makes sure
+ * the sandbox has an SSH server and this machine has the `*.runtime` ssh
+ * entry, then hands the editor the SSH remote. */
+export async function editorCommand(argv, env, out, connect, me) {
+    const valueOf = (flag) => {
+        const at = argv.indexOf(flag);
+        return at === -1 ? undefined : argv[at + 1];
+    };
+    const editor = (valueOf("--editor") ?? "vscode").toLowerCase().replace(/^code$/, "vscode");
+    const path = valueOf("--path") ?? "/workspace";
+    const valued = new Set(["--editor", "--path"]);
+    const [target] = argv.filter((word, i) => !word.startsWith("--") && !valued.has(argv[i - 1] ?? ""));
+    if (!target || target === "help") {
+        out.write(SSH_HELP(me));
+        return target ? 0 : 64;
+    }
+    if (!(editor in EDITORS))
+        throw new RuntimeError({
+            message: `${editor} is not an editor this opens.`,
+            code: "usage",
+            status: 0,
+            hint: `Use --editor ${Object.keys(EDITORS).join(", --editor ")}; JetBrains Gateway connects to <id>.runtime after \`${me} sandboxes ssh config --install\`.`,
+        });
+    if (!path.startsWith("/"))
+        throw usageError(`--path is a folder in the sandbox, from /: ${path}`, me);
+    const sbx = await resolveSandbox(await connect(), target);
+    await ensureSshd(sbx, out);
+    await installConfig(env);
+    const how = editorLaunch(editor, sbx.id, path);
+    const { name } = EDITORS[editor];
+    const print = argv.includes("--print");
+    // Without the editor's program on the PATH (VS Code's `code` is opt-in on a
+    // Mac), the desktop opens the editor's link.
+    const [opener, ...openerArgs] = process.platform === "darwin"
+        ? ["open", how.link]
+        : process.platform === "win32"
+            ? ["cmd", "/c", "start", '""', how.link]
+            : ["xdg-open", how.link];
+    const opened = print
+        ? false
+        : (await launched(how.bin, how.args, env))
+            ? "program"
+            : (await launched(opener, openerArgs, env))
+                ? "link"
+                : false;
+    if (out.json)
+        out.write(JSON.stringify({ sandboxId: sbx.id, editor, host: how.host, path, link: how.link, opened }));
+    else if (opened)
+        out.write(`Opening ${path} of ${sbx.id} in ${name} over SSH (host ${how.host}). It needs ${name === "VS Code" ? "the Remote - SSH extension" : "its Remote - SSH extension"}; the first connection installs the editor's server in the sandbox.`);
+    else
+        out.write(`${print ? "" : `Could not start ${how.bin} or open a link here. `}Open this link on this machine:\n${how.link}\nor run: ${how.bin} ${how.args.join(" ")}`);
+    return opened || print ? 0 : 1;
+}
 /** `runtime sandboxes port-forward <id> 5432 8080:3000 ...` */
 export async function portForwardCommand(argv, out, connect, me) {
     const at = argv.indexOf("--address");