fix: update sandbox apis (#2829)

kt3k · magurotuna · web-flow · commit 354d1202c24b · 2026-01-14T15:59:02.000+09:00
Co-authored-by: Yusuke Tanaka &lt;wing0920@gmail.com&gt;
diff --git a/examples/_data.ts b/examples/_data.ts
@@ -374,8 +374,8 @@ export const sidebar = [
         type: "example",
       },
       {
-        title: "Control sandbox lifetime",
-        href: "/examples/sandboxes_lifetime_control/",
+        title: "Control sandbox timeout",
+        href: "/examples/sandboxes_timeout_control/",
         type: "example",
       },
       {
diff --git a/examples/sandboxes/evaluating_javascript.md b/examples/sandboxes/evaluating_javascript.md
@@ -12,7 +12,7 @@ import { Sandbox } from "@deno/sandbox";
 
 await using sandbox = await Sandbox.create();
 
-const result = await sandbox.eval(`
+const result = await sandbox.deno.eval(`
   const a = 1;
   const b = 2;
   a + b;
diff --git a/examples/sandboxes/javascript_repl.md b/examples/sandboxes/javascript_repl.md
@@ -1,23 +1,23 @@
 ---
 title: "Intereactive JavaScript REPL"
-description: "Learn how to provide an interactive JavaScript REPL in a sandbox."
+description: "Learn how to provide an interactive Deno REPL in a sandbox."
 url: /examples/sandboxes_javascript_repl/
 layout: sandbox-example.tsx
 ---
 
-The `sandbox.repl()` method can be used to provide an interactive JavaScript
-REPL in a sandbox.
+The `sandbox.deno.repl()` method can be used to provide an interactive Deno REPL
+in a sandbox.
 
-This example shows how to start a JavaScript REPL in a sandbox and execute code
+This example shows how to start a Deno REPL in a sandbox and execute code
 interactively.
 
 ```ts
 import { Sandbox } from "@deno/sandbox";
 
 await using sandbox = await Sandbox.create();
 
-// Start a JavaScript REPL
-const repl = await sandbox.repl();
+// Start a Deno REPL
+const repl = await sandbox.deno.repl();
 
 // Execute code interactively, maintaining state
 await repl.eval("const x = 42;");
diff --git a/examples/sandboxes/memory.md b/examples/sandboxes/memory.md
@@ -23,7 +23,7 @@ import { Sandbox } from "@deno/sandbox";
 await using sandbox = await Sandbox.create({ memoryMb: 4096 });
 
 // Check available memory
-const memInfo = await sandbox.eval<{ total: number }>(
+const memInfo = await sandbox.deno.eval<{ total: number }>(
   "Deno.systemMemoryInfo()",
 );
 console.log("Total memory:", memInfo.total);
diff --git a/examples/sandboxes/stream_output.md b/examples/sandboxes/stream_output.md
@@ -20,7 +20,7 @@ import { Writable } from "node:stream";
 await using sandbox = await Sandbox.create();
 
 // Create a large file in the sandbox
-await sandbox.writeTextFile("big.txt", "#".repeat(5_000_000));
+await sandbox.fs.writeTextFile("big.txt", "#".repeat(5_000_000));
 
 // Stream it out to a local file
 const child = await sandbox.spawn("cat", {
diff --git a/examples/sandboxes/timeout_control.md b/examples/sandboxes/timeout_control.md
@@ -1,17 +1,17 @@
 ---
-title: "Control sandbox lifetime"
-description: "Learn how to control how long your sandbox stays alive using the lifetime option."
-url: /examples/sandboxes_lifetime_control/
+title: "Control sandbox timeout"
+description: "Learn how to control how long your sandbox stays alive using the timeout option."
+url: /examples/sandboxes_timeout_control/
 layout: sandbox-example.tsx
 ---
 
-You can control how long your sandbox stays alive using the lifetime option:
+You can control how long your sandbox stays alive using the timeout option:
 
 ```ts
 import { Sandbox } from "@deno/sandbox";
 
 // Default: "session" - sandbox shuts down when you close/dispose the client
-await using sandbox = await Sandbox.create({ lifetime: "session" });
+await using sandbox = await Sandbox.create({ timeout: "session" });
 ```
 
 Supported duration suffixes: `s` (seconds), `m` (minutes).
@@ -23,7 +23,7 @@ import { Sandbox } from "@deno/sandbox";
 
 // Duration-based: keep sandbox alive for a specific time period
 // Useful when you want the sandbox to persist after the script exits
-const sandbox = await Sandbox.create({ lifetime: "5m" }); // 5 minutes
+const sandbox = await Sandbox.create({ timeout: "5m" }); // 5 minutes
 const id = sandbox.id;
 // Close the *connection* to the sandbox; the sandbox keeps running
 await sandbox.close();
@@ -32,10 +32,10 @@ await sandbox.close();
 const reconnected = await Sandbox.connect({ id });
 await reconnected.sh`echo 'Still alive!'`;
 
-// You can still forcibly terminate it before its lifetime expires
+// You can still forcibly terminate it before its timeout elapses
 await reconnected.kill();
 // At this point, the sandbox is no longer reconnectable
 ```
 
-> Need other lifetime modes? Contact
+> Need other timeout modes? Contact
 > <a href="mailto:deploy@deno.com">deploy@deno.com</a>.
diff --git a/examples/sandboxes/upload_files.md b/examples/sandboxes/upload_files.md
@@ -6,16 +6,16 @@ layout: sandbox-example.tsx
 ---
 
 Copy files from your machine into the sandbox using
-`sandbox.upload(localPath, sandboxPath)`.
+`sandbox.fs.upload(localPath, sandboxPath)`.
 
 ```ts
 import { Sandbox } from "@deno/sandbox";
 
 await using sandbox = await Sandbox.create();
 
 // Upload a single file to a specific path in the sandbox
-await sandbox.upload("./README.md", "./readme-copy.md");
+await sandbox.fs.upload("./README.md", "./readme-copy.md");
 
 // Upload a local directory tree into the sandbox current directory
-await sandbox.upload("./my-project", ".");
+await sandbox.fs.upload("./my-project", ".");
 ```
diff --git a/examples/sandboxes/vscode_instance.md b/examples/sandboxes/vscode_instance.md
@@ -5,8 +5,8 @@ url: /examples/sandboxes_vscode_instance/
 layout: sandbox-example.tsx
 ---
 
-The `sandbox.vscode()` method can be used to provide a VSCode instance in a
-sandbox.
+The `sandbox.exposeVscode()` method can be used to provide a VSCode instance in
+a sandbox.
 
 This example shows how to start a VSCode instance in a sandbox and print the url
 of the running instance which you can then open in your browser.
@@ -17,7 +17,7 @@ import { Sandbox } from "@deno/sandbox";
 await using sandbox = await Sandbox.create();
 
 // Start a VSCode instance
-const vscode = await sandbox.vscode();
+const vscode = await sandbox.exposeVscode();
 
 console.log(vscode.url); // print the url of the running instance
 await vscode.status; // wait until it exits
diff --git a/examples/sandboxes/web_framework.md b/examples/sandboxes/web_framework.md
@@ -23,12 +23,12 @@ const PACKAGE_JSON = {
   type: "module",
   dependencies: { express: "^4.19.2" },
 };
-await sandbox.writeTextFile(
+await sandbox.fs.writeTextFile(
   "package.json",
   JSON.stringify(PACKAGE_JSON, null, 2),
 );
 
-await sandbox.writeTextFile(
+await sandbox.fs.writeTextFile(
   "server.js",
   `import express from 'express';
 const app = express();
@@ -42,7 +42,7 @@ app.listen(3000, () => console.log('listening on :3000'));
 await sandbox.sh`deno install`;
 
 // 3) Start the server
-const server = await sandbox.createJsRuntime({ entrypoint: "server.js" });
+const server = await sandbox.deno.run({ entrypoint: "server.js" });
 
 // 4) Publish to the internet
 const publicUrl = await sandbox.exposeHttp({ port: 3000 });
diff --git a/sandboxes/_data.ts b/sandboxes/_data.ts
@@ -39,8 +39,8 @@ export const sidebar = [
         href: "/sandboxes/volumes/",
       },
       {
-        title: "Lifetimes",
-        href: "/sandboxes/lifetimes/",
+        title: "Timeouts",
+        href: "/sandboxes/timeouts/",
       },
       {
         title: "Security",
diff --git a/sandboxes/cli.md b/sandboxes/cli.md
@@ -46,7 +46,7 @@ deno sandbox create --lifetime 2m
 You can also create a sandbox with a custom memory limit:
 
 ```bash
-deno sandbox create --memory 2gb
+deno sandbox create --memory 2gib
 ```
 
 To expose HTTP ports for web applications:
@@ -224,7 +224,7 @@ across sandbox instances. Use the `deno sandbox volumes` command to manage them.
 Create a new volume with a specific name, capacity, and region:
 
 ```bash
-deno sandbox volumes create --name my-data --capacity 10gb --region ord
+deno sandbox volumes create my-data --capacity 10gb --region ord
 ```
 
 ### Listing Volumes
@@ -264,12 +264,12 @@ additional software as needed. The sandbox continues running after you
 disconnect, so you can reconnect later or use other commands to interact with it
 remotely.
 
-## Managing Sandbox Lifetime
+## Managing Sandbox Timeout
 
 ### Extending Sandbox Duration
 
 Sometimes you'll need more time to complete your work in a running sandbox. The
-`deno sandbox extend` command allows you to extend the lifetime of any running
+`deno sandbox extend` command allows you to extend the timeout of any running
 sandbox without interrupting ongoing processes:
 
 ```bash
diff --git a/sandboxes/create.md b/sandboxes/create.md
@@ -15,7 +15,7 @@ await using sandbox = await Sandbox.create();
 ```
 
 By default, this creates an ephemeral sandbox in the closest Deploy region with
-1280 MB of RAM, no outbound network access, and a lifetime bound to the current
+1280 MB of RAM, no outbound network access, and a timeout bound to the current
 process. You can tailor the sandbox by passing an options object.
 
 ## Available options
@@ -25,7 +25,7 @@ process. You can tailor the sandbox by passing an options object.
 | `region`   | Eg `ams` or `ord`                                                                                                       |
 | `allowNet` | Array of hosts that can receive requests from the sandbox. If specified, any hosts not listed are unreachable.          |
 | `memoryMb` | Allocate between 768 and 4096 MB of RAM for memory-heavy tasks or tighter budgets.                                      |
-| `lifetime` | [How long the sandbox stays alive](./lifetimes) in (m) or (s) such as `5m`                                              |
+| `timeout`  | [How long the sandbox stays alive](./timeouts) in (m) or (s) such as `5m`                                               |
 | `labels`   | Attach arbitrary key/value labels to help identify and manage sandboxes                                                 |
 | `env`      | Set initial environment variables inside the sandbox. Secrets should still be managed via Deploy’s secret substitution. |
 
@@ -51,7 +51,7 @@ const sandbox = await Sandbox.create({
 ### Keep the sandbox alive for later inspection
 
 ```tsx
-const sandbox = await Sandbox.create({ lifetime: "10m" });
+const sandbox = await Sandbox.create({ timeout: "10m" });
 const id = sandbox.id;
 await sandbox.close(); // disconnect but leave VM running
 
diff --git a/sandboxes/expose_http.md b/sandboxes/expose_http.md
@@ -7,11 +7,11 @@ You can run dev servers, preview apps, webhook receivers, or framework CLIs on
 any port and publish them instantly to a secure, random HTTPS URL.
 
 ```tsx
-await sandbox.writeTextFile(
+await sandbox.fs.writeTextFile(
   "server.js",
   "Deno.serve(() => new Response('Hello from Sandboxes'));",
 );
-const runtime = await sandbox.createJsRuntime({ entrypoint: "server.js" });
+const runtime = await sandbox.deno.run({ entrypoint: "server.js" });
 const publicUrl = await sandbox.exposeHttp({ port: 8000 });
 console.log(publicUrl); // https://<random>.sandbox.deno.net
 ```
@@ -78,7 +78,7 @@ import { Sandbox } from "@deno/sandbox";
 await using sandbox = await Sandbox.create();
 
 // Install dependencies
-await sandbox.writeTextFile(
+await sandbox.fs.writeTextFile(
   "package.json",
   JSON.stringify(
     {
diff --git a/sandboxes/expose_ssh.md b/sandboxes/expose_ssh.md
@@ -12,17 +12,17 @@ import { Sandbox } from "@deno/sandbox";
 
 await using sandbox = await Sandbox.create();
 
-const { hostname, username, privateKey } = await sandbox.exposeSsh();
+const { hostname, username } = await sandbox.exposeSsh();
 console.log(`ssh ${username}@${hostname}`);
 
 // keep process alive or interact via SSH until done...
 await new Promise((resolve) => setTimeout(resolve, 10 * 60 * 1000));
 ```
 
-The sandbox remains reachable for the configured lifetime. Once your script
-releases its references (for example, the `await using` block ends) the sandbox
-shuts down and the SSH endpoint disappears; you can also call `sandbox.kill()`
-if you need to tear it down immediately.
+The sandbox remains reachable until the configured timeout expires. Once your
+script releases its references (for example, the `await using` block ends) the
+sandbox shuts down and the SSH endpoint disappears; you can also call
+`sandbox.kill()` if you need to tear it down immediately.
 
 ## When to use SSH access
 
@@ -37,15 +37,13 @@ projects or organizations.
 ## Connecting from your machine
 
 1. Request credentials via `sandbox.exposeSsh()`.
-2. Store the returned `privateKey` (or `identityFile`) to a temporary file with
-   `chmod 600` permissions.
-3. Connect using the provided username and hostname:
+2. Connect using the provided username and hostname:
 
 ```bash
-ssh -i ./sandbox-key ${username}@${hostname}
+ssh ${username}@${hostname}
 ```
 
-4. Use regular terminal workflows: copy files, run top, tail logs, or attach to
+3. Use regular terminal workflows: copy files, run top, tail logs, or attach to
    running processes.
 
 :::tip
@@ -65,9 +63,8 @@ servers that are bound to `localhost` inside the sandbox.
 
 The SSH tunnel closes if the sandbox shuts down. Keep it running by:
 
-- Setting `lifetime: "session"` (default) and keeping your managing script
-  active
-- Passing `lifetime: "5m"` (or another duration) when creating the sandbox so it
+- Setting `timeout: "session"` (default) and keeping your managing script active
+- Passing `timeout: "5m"` (or another duration) when creating the sandbox so it
   persists after the script exits, then reconnecting later with
   `Sandbox.connect({ id })`
 
@@ -79,21 +76,17 @@ end it on demand.
 
 ```tsx
 import { Sandbox } from "@deno/sandbox";
-import { writeTextFile } from "node:fs/promises";
 
-await using sandbox = await Sandbox.create({ lifetime: "10m" });
+await using sandbox = await Sandbox.create({ timeout: "10m" });
 
 // Prepare the app
-await sandbox.upload("./app", ".");
+await sandbox.fs.upload("./app", ".");
 await sandbox.sh`deno task dev`
   .noThrow(); // start server; leave running for inspection
 
-// Get SSH details and write key to disk
+// Get SSH details
 const ssh = await sandbox.exposeSsh();
-await writeTextFile("./sandbox-key", ssh.privateKey);
-await sandbox.sh`chmod 600 sandbox-key`;
-
-console.log(`Connect with: ssh -i sandbox-key ${ssh.username}@${ssh.hostname}`);
+console.log(`Connect with: ssh ${ssh.username}@${ssh.hostname}`);
 
 // Block until you're done debugging manually
 await new Promise((resolve) => setTimeout(resolve, 10 * 60 * 1000));
diff --git a/sandboxes/getting_started.md b/sandboxes/getting_started.md
diff --git a/sandboxes/index.md b/sandboxes/index.md
diff --git a/sandboxes/manage_apps.md b/sandboxes/manage_apps.md
diff --git a/sandboxes/promote.md b/sandboxes/promote.md
diff --git a/sandboxes/timeouts.md b/sandboxes/timeouts.md
diff --git a/sandboxes/volumes.md b/sandboxes/volumes.md

Original file line number	Diff line number	Diff line change
`@@ -374,8 +374,8 @@ export const sidebar = [`
`374`	`374`	`type: "example",`
`375`	`375`	`},`
`376`	`376`	`{`
`377`		`- title: "Control sandbox lifetime",`
`378`		`- href: "/examples/sandboxes_lifetime_control/",`
	`377`	`+ title: "Control sandbox timeout",`
	`378`	`+ href: "/examples/sandboxes_timeout_control/",`
`379`	`379`	`type: "example",`
`380`	`380`	`},`
`381`	`381`	`{`
Original file line number	Diff line number	Diff line change
`@@ -39,8 +39,8 @@ export const sidebar = [`
`39`	`39`	`href: "/sandboxes/volumes/",`
`40`	`40`	`},`
`41`	`41`	`{`
`42`		`- title: "Lifetimes",`
`43`		`- href: "/sandboxes/lifetimes/",`
	`42`	`+ title: "Timeouts",`
	`43`	`+ href: "/sandboxes/timeouts/",`
`44`	`44`	`},`
`45`	`45`	`{`
`46`	`46`	`title: "Security",`