withruntime 0.8.0 → 0.8.1

package/BLAXEL.md

@@ -24,15 +24,26 @@ anywhere: in `BL_API_KEY` it is ignored, and passed to `initialize` while
 nothing on Runtime. With no Runtime key at all, the first call throws
 `CredentialsError` saying what to set.
 
+**A key sees only the sandboxes it created.** A sandbox made with another of
+the account's keys answers 404, though its name stays taken
+([teams](https://withruntime.com/docs/teams)). Services that share sandboxes by
+name, or through `getByExternalId`, use the same Runtime key.
+
 ## What a sandbox gets
 
 - **Machine:** Blaxel's default of 4096 MB. vCPUs follow Blaxel's rule of one
-  per 2048 MB (at least one, at most 16): 2 for the default, 4 for 8192 MB.
+  per 2048 MB (at least one, at most 16): 2 for the default, 4 for 8192 MB. A
+  trial sandbox has at most 4096 MB (2 vCPUs); `memory: 8192` or more needs
+  prepaid credit, and on the trial is refused with a 400 (`invalid_trial`)
+  saying so.
 - **Image:** Blaxel's `base-image`, `py-app`, `ts-app`, `node`,
   `docker-in-sandbox` and `jupyter-server` are Runtime's stock image (Ubuntu
   24.04 with Node.js 24, Python 3.12, Bun, git and a compiler; Docker after
-  `sudo enable-docker`). Any other name must be a ready Runtime image with that
-  name.
+  `sudo enable-docker`). Any other image `ns/name:tag` is the ready Runtime
+  image named `ns-name` (every `/` becomes `-`, as Runtime names hold none) at
+  tag `tag` (`latest` when none is given). Build it once with
+  `npx withruntime image build --dockerfile Dockerfile --name ns-name -t ns-name:tag`,
+  and the code keeps `image: "ns/name:tag"` as it is.
 - **Standby and lifetime:** a Blaxel sandbox goes to standby when unused and
   resumes on the next call. On Runtime it pauses after 60 seconds without a
   call (Runtime's shortest idle pause; Blaxel's is about 15 seconds), keeping
@@ -107,21 +118,21 @@ nothing on Runtime. With no Runtime key at all, the first call throws
 Each of these throws `NotSupportedError` before anything happens. Its `feature`
 names the gap and its `alternative` says what to use.
 
-| Blaxel                                                                                                                   | Use instead                                                                                                             |
-| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| An `image` with no Runtime image of that name (Blaxel's other templates too)                                             | Build it: `npx withruntime image build --dockerfile Dockerfile --name <image>`.                                         |
-| A region outside the US                                                                                                  | Runtime runs in one US region.                                                                                          |
-| `extraArgs` other than `iptables`; network `egress`, `firewall`, `subnet`, and a `proxy` with more than its domain lists | Remove them; `allowedDomains` and `forbiddenDomains` (on the network or its proxy); Runtime secrets.                    |
-| Read-only and ephemeral volumes; a volume with no Runtime volume of that name                                            | Mount read-write; write scratch files under `/workspace`; `runtime.volumes.create`.                                     |
-| `snapshots.restore`, `restore`                                                                                           | Fork from the snapshot into a new sandbox.                                                                              |
-| Forking into an application                                                                                              | Fork into a sandbox and share its port.                                                                                 |
-| A preview's `prefixUrl`, `customDomain`, `requestHeaders`, `responseHeaders`, `ttl`                                      | Runtime's fixed preview address; set headers (CORS) in your server; delete the preview.                                 |
-| `preview.tokens.list()`; a token for over a week                                                                         | Keep the tokens you create; create a new one when it runs out.                                                          |
-| `runCode` with `envs` for one run; a language Runtime's interpreter lacks                                                | Sandbox envs at create, or set them in the code; `process.exec`.                                                        |
-| Listing by `cursor`, `q`, `anchor`, a status other than `DEPLOYED`, or newest first                                      | List and filter the result yourself; `nextPage()` walks the pages.                                                      |
-| `sandbox.sessions`, `schedules`, `codegen`, `system`, `drives`; `fromSession`                                            | Previews and tokens; your own scheduler; `fs.write`; nothing to upgrade; Runtime volumes.                               |
-| Agents, models, tools, MCP transports, jobs, applications, images, volumes, drives                                       | Your own agent with Runtime sandboxes, `withruntime/tools`, `npx withruntime mcp`, `runtime.images`, `runtime.volumes`. |
-| Blaxel's generated API functions (`createSandbox`, `postProcess`, ...)                                                   | `SandboxInstance` here, or `import { Runtime } from "withruntime"`.                                                     |
+| Blaxel                                                                                                                   | Use instead                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| An `image` with no ready Runtime image of the name it maps to (Blaxel's other templates too)                             | Build it: `npx withruntime image build --dockerfile Dockerfile --name ns-name -t ns-name:tag`; the error gives the exact command. |
+| A region outside the US                                                                                                  | Runtime runs in one US region.                                                                                                    |
+| `extraArgs` other than `iptables`; network `egress`, `firewall`, `subnet`, and a `proxy` with more than its domain lists | Remove them; `allowedDomains` and `forbiddenDomains` (on the network or its proxy); Runtime secrets.                              |
+| Read-only and ephemeral volumes; a volume with no Runtime volume of that name                                            | Mount read-write; write scratch files under `/workspace`; `runtime.volumes.create`.                                               |
+| `snapshots.restore`, `restore`                                                                                           | Fork from the snapshot into a new sandbox.                                                                                        |
+| Forking into an application                                                                                              | Fork into a sandbox and share its port.                                                                                           |
+| A preview's `prefixUrl`, `customDomain`, `requestHeaders`, `responseHeaders`, `ttl`                                      | Runtime's fixed preview address; set headers (CORS) in your server; delete the preview.                                           |
+| `preview.tokens.list()`; a token for over a week                                                                         | Keep the tokens you create; create a new one when it runs out.                                                                    |
+| `runCode` with `envs` for one run; a language Runtime's interpreter lacks                                                | Sandbox envs at create, or set them in the code; `process.exec`.                                                                  |
+| Listing by `cursor`, `q`, `anchor`, a status other than `DEPLOYED`, or newest first                                      | List and filter the result yourself; `nextPage()` walks the pages.                                                                |
+| `sandbox.sessions`, `schedules`, `codegen`, `system`, `drives`; `fromSession`                                            | Previews and tokens; your own scheduler; `fs.write`; nothing to upgrade; Runtime volumes.                                         |
+| Agents, models, tools, MCP transports, jobs, applications, images, volumes, drives                                       | Your own agent with Runtime sandboxes, `withruntime/tools`, `npx withruntime mcp`, `runtime.images`, `runtime.volumes`.           |
+| Blaxel's generated API functions (`createSandbox`, `postProcess`, ...)                                                   | `SandboxInstance` here, or `import { Runtime } from "withruntime"`.                                                               |
 
 Some differences are not refusals:
 

package/dist/blaxel/errors.js

@@ -82,6 +82,27 @@ export function responseError(status, message) {
         headers: { "content-type": "application/json" },
     }), data, data);
 }
+const LS = "List the directory with sandbox.fs.ls(path).";
+/** Runtime's hints that name Runtime's calls, in the Blaxel calls a Blaxel
+ * program makes (the Python adapter uses the same words). */
+const AGAIN = "Try again in a moment.";
+const BLAXEL_HINTS = {
+    name_taken: "SandboxInstance.createIfNotExists({ name }) answers the sandbox that has the name.",
+    file_not_found: LS,
+    path_not_found: LS,
+    is_a_directory: "That path is a directory: list it with sandbox.fs.ls(path), or name a file in it.",
+    cwd_not_found: "Make the directory with sandbox.fs.mkdir(path), or pass an existing workingDir to sandbox.process.exec.",
+    sandbox_paused: "Call sandbox.unarchive(), then try again.",
+    not_running: "The sandbox is not running: call sandbox.unarchive() if it was archived, or make a new one with SandboxInstance.create if it was deleted.",
+    trial_busy: "The trial's sandboxes are all in use: delete one you no longer need (sandbox.delete()) or archive it (sandbox.archive()), then try again. Moving to paid credit is the account owner's decision.",
+    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt). A public preview needs a paid sandbox, which is the account owner's decision.",
+    busy: AGAIN,
+    guest_busy: AGAIN,
+    rate_limited: AGAIN,
+    unauthorized: "Set RUNTIME_API_KEY to a Runtime key (https://withruntime.com/account/keys), or run `npx withruntime login` once. A Blaxel key (BL_API_KEY) is never sent.",
+};
+/** A trial create over the trial's size, in Blaxel's field. */
+const TRIAL_CAP = "A trial sandbox has at most 4096 MB of memory (2 vCPUs); pass memory 4096 or add credit.";
 /** A Runtime SDK error as Blaxel's: ResponseError (SandboxGatewayError for a
  * 502, 503 or 504), NotSupportedError for a product Runtime has switched off,
  * CredentialsError when there is no Runtime key. Anything else passes through
@@ -97,9 +118,11 @@ export function translate(error) {
         return new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", error.message);
     if (error.status < 200 || error.status > 599)
         return error;
+    const trialCap = error.code === "invalid_trial";
+    const hint = trialCap ? undefined : (BLAXEL_HINTS[error.code] ?? error.hint);
     const message = [
-        error.message,
-        error.hint ? `Hint: ${error.hint}` : "",
+        trialCap ? TRIAL_CAP : error.message,
+        hint ? `Hint: ${hint}` : "",
         error.requestId ? `Request: ${error.requestId}` : "",
     ]
         .filter(Boolean)
@@ -107,7 +130,7 @@ export function translate(error) {
     const data = {
         error: message,
         code: error.code,
-        ...(error.hint ? { hint: error.hint } : {}),
+        ...(hint ? { hint } : {}),
         ...(error.requestId ? { requestId: error.requestId } : {}),
     };
     const Kind = GATEWAY.has(error.status) ? SandboxGatewayError : ResponseError;
@@ -116,8 +139,8 @@ export function translate(error) {
         headers: { "content-type": "application/json" },
     }), data, data);
     out.runtimeCode = error.code;
-    if (error.hint)
-        out.hint = error.hint;
+    if (hint)
+        out.hint = hint;
     if (error.requestId)
         out.requestId = error.requestId;
     out.cause = error;

package/dist/blaxel/index.d.ts

@@ -1,5 +1,5 @@
 import { type Config } from "./client.js";
-export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durationMs, lifetimeOf, networkRules, type SandboxListQuery, type SandboxForkOptions, type SandboxArchiveOptions, } from "./sandbox.js";
+export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durationMs, imageRef, lifetimeOf, networkRules, type SandboxListQuery, type SandboxForkOptions, type SandboxArchiveOptions, } from "./sandbox.js";
 export { CodeInterpreter } from "./interpreter.js";
 export { SandboxFileSystem, retryOnTransient, type File, type FileWithContent, type Subdirectory, type Directory, type SuccessResponse, type FindMatch, type FindResponse, type FuzzySearchMatch, type FuzzySearchResponse, type ContentSearchMatch, type ContentSearchResponse, type CopyResponse, type WatchEvent, type SandboxFilesystemFile, type FilesystemSearchOptions, type FilesystemFindOptions, type FilesystemGrepOptions, } from "./filesystem.js";
 export { SandboxProcess, type ProcessRequest, type ProcessResponse, type ProcessRequestWithLog, type ProcessResponseWithLog, type PostProcessResponse, type GetProcessResponse, type GetProcessByIdentifierResponse, type DeleteProcessByIdentifierResponse, type DeleteProcessByIdentifierKillResponse, type ProcessLogs, } from "./process.js";

package/dist/blaxel/index.js

@@ -11,7 +11,7 @@ import { RuntimeError } from "../errors.js";
 import { initialize } from "./client.js";
 import { NotSupportedError } from "./errors.js";
 import { CODEGEN, DRIVES, SCHEDULES, SESSIONS, SYSTEM, unsupportedExport } from "./unsupported.js";
-export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durationMs, lifetimeOf, networkRules, } from "./sandbox.js";
+export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durationMs, imageRef, lifetimeOf, networkRules, } from "./sandbox.js";
 export { CodeInterpreter } from "./interpreter.js";
 export { SandboxFileSystem, retryOnTransient, } from "./filesystem.js";
 export { SandboxProcess, } from "./process.js";

package/dist/blaxel/sandbox.d.ts

@@ -72,6 +72,13 @@ export declare function lifetimeOf(asked: {
  * domains, from the network itself or from its proxy (Blaxel's current
  * place for them). Anything else of the proxy is refused. */
 export declare function networkRules(network: SandboxNetwork): NonNullable<RuntimeCreate["network"]>;
+/** A Blaxel image `ns/name:tag` as the Runtime image name and tag it maps to
+ * (Runtime names allow no "/"): every "/" becomes "-" (`ns-name`), and the
+ * tag is `latest` when none is given. The Python adapter maps the same way. */
+export declare function imageRef(image: string): {
+    name: string;
+    tag: string;
+};
 /** A sandbox with Blaxel's methods. `sandbox.withruntime` is the Runtime
  * sandbox underneath, for anything Blaxel has no name for. */
 export declare class SandboxInstance {

package/dist/blaxel/sandbox.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 import { clientFor, defaultRegion, } from "./client.js";
 import { checkEnvNames, envFileCommand, envFileLines, parseProcessLine, toRuntimePath, } from "./context.js";
 import { codeOf, guard, NotSupportedError, responseError, translate } from "./errors.js";
@@ -178,26 +179,38 @@ function checkRegion(region) {
     if (region !== undefined && region !== "" && !US_REGIONS.has(region))
         throw new NotSupportedError(`The region ${region}`, "Runtime runs in one US region: remove region (and BL_REGION), or use us-was-1.");
 }
-/** Where an image sends the create: Runtime's stock image, or a ready Runtime
- * image by name or id. */
+/** A Blaxel image `ns/name:tag` as the Runtime image name and tag it maps to
+ * (Runtime names allow no "/"): every "/" becomes "-" (`ns-name`), and the
+ * tag is `latest` when none is given. The Python adapter maps the same way. */
+export function imageRef(image) {
+    const slash = image.lastIndexOf("/");
+    const colon = image.lastIndexOf(":");
+    const [name, tag] = colon > slash ? [image.slice(0, colon), image.slice(colon + 1)] : [image, ""];
+    return { name: name.replaceAll("/", "-"), tag: tag || "latest" };
+}
+/** Where an image sends the create: Runtime's stock image, or the ready
+ * Runtime image `imageRef` maps it to. */
 async function resolveImage(client, image) {
     if (image === undefined || STOCK_IMAGE.test(image))
         return {};
     if (UUID.test(image))
         return { image };
-    const name = image.replace(/:latest$/, "");
+    const { name, tag } = imageRef(image);
     let found;
     try {
-        found = (await client.images.list({ name, state: "ready", limit: 1 })).data[0];
+        found = await client.images.resolve(`${name}:${tag}`);
     }
     catch (error) {
-        // A name Runtime could not hold is simply not one of its images.
-        if (codeOf(error) !== "invalid_request")
+        // Not an image, or a name Runtime could not hold: the same answer.
+        const status = error instanceof RuntimeError ? error.status : undefined;
+        if (status !== 400 && status !== 404)
             throw translate(error);
     }
-    if (found)
+    if (found && found.state === "ready")
         return { image: found.id };
-    throw new NotSupportedError(`The image ${image}, which is not a Runtime image`, `Build it as a Runtime image with that name and this call starts from it: \`npx withruntime image build --dockerfile Dockerfile --name ${name}\`, or runtime.images.build({ name: "${name}", image: "<registry reference>" }).`);
+    const feature = `The image ${image}, which is not a Runtime image`;
+    const alternative = `Build it as a Runtime image named ${name}: \`npx withruntime image build --dockerfile Dockerfile --name ${name} -t ${name}:${tag}\`. The code can keep "${image}": the adapter starts from ${name}:${tag}.`;
+    throw new NotSupportedError(feature, alternative, `${feature}, is not supported on Runtime. ${alternative}`);
 }
 /** Blaxel volumes (by name) as Runtime volumes. */
 async function resolveVolumes(client, volumes) {

package/dist/cli.js

@@ -2150,8 +2150,8 @@ async function snapshot(argv, env, out) {
 }
 const IMAGE_HELP = `runtime image <command>
 
-  build [<folder>] [-f <Dockerfile>] | --from <image> | --pip <pkg>... --apt <pkg>... --npm <pkg>...
-        [-t name[:tag]]... [--target <stage>] [--build-arg K=V]... [--no-cache]
+  build [<folder>] [--dockerfile|-f <Dockerfile>] | --from <image> | --pip <pkg>... --apt <pkg>... --npm <pkg>...
+        [--name <name>] [--tag|-t name[:tag]]... [--target <stage>] [--build-arg K=V]... [--no-cache]
         [--start <command>] [--ready-port <port> | --ready-command <command>]
         [--max-image-mib 8192] [--disk-mib <1024-32768>] [--timeout <seconds>]
                         Build and stream the log; prints the image id when ready.

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.8.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.8.0";
+export const VERSION = "0.8.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",