@alchemy.run/e2b 0.0.0 → 2.0.0-beta.87

package/src/CreateSandbox.ts

@@ -0,0 +1,157 @@
+import type * as sandboxes from "@distilled.cloud/e2b/sandboxes";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { BoundVolumeMount, VolumeMount } from "./MountVolume.ts";
+import type { E2BError, E2BSandbox } from "./SandboxClient.ts";
+import type { Snapshot } from "./Snapshot.ts";
+import type { Template } from "./Template.ts";
+
+/** A template or snapshot sandboxes are created from. */
+export type SandboxBase = Template | Snapshot;
+
+/**
+ * E2B's `createSandbox` parameters. `templateID` defaults to the bound base;
+ * `metadata` is merged with the host's ownership stamp; `mounts` replaces
+ * E2B's `volumeMounts`.
+ */
+export type CreateSandboxOptions = Omit<
+  sandboxes.CreateSandboxRequest,
+  "templateID" | "volumeMounts"
+> & {
+  readonly templateID?: string;
+  /**
+   * Volumes to mount: a volume `CreateVolume` returned with a `path`, or a
+   * reference from `E2B.MountVolume`. A bound template's own mounts are
+   * added.
+   */
+  readonly mounts?: ReadonlyArray<VolumeMount | BoundVolumeMount>;
+};
+
+/** E2B's `listSandboxes` filters, with `metadata` as a record instead of a query string. */
+export type ListSandboxesOptions = Omit<
+  sandboxes.ListSandboxesRequest,
+  "metadata" | "nextToken"
+> & {
+  readonly metadata?: Readonly<Record<string, string>>;
+};
+
+/** E2B sandboxes: create, look up, list and kill them. */
+export interface SandboxesClient {
+  /** Creates a sandbox from the bound base (or `templateID`). */
+  create(options?: CreateSandboxOptions): Effect.Effect<E2BSandbox, E2BError, RuntimeContext>;
+  /**
+   * A handle to an existing sandbox. A paused sandbox is resumed; `timeout`
+   * (seconds) resets its lifetime.
+   */
+  connect(
+    sandboxId: string,
+    options?: { readonly timeout?: number; readonly memory?: boolean },
+  ): Effect.Effect<E2BSandbox, E2BError, RuntimeContext>;
+  /** A sandbox's details, without resuming it. */
+  get(sandboxId: string): Effect.Effect<sandboxes.SandboxDetail, E2BError, RuntimeContext>;
+  /** Sandboxes, filtered by metadata, state or template (the bound base by default). */
+  list(
+    options?: ListSandboxesOptions,
+  ): Effect.Effect<ReadonlyArray<sandboxes.ListedSandbox>, E2BError, RuntimeContext>;
+  /** Kills a sandbox. Killing one that is gone succeeds. */
+  kill(sandboxId: string): Effect.Effect<void, E2BError, RuntimeContext>;
+  /** The latest CPU, memory and disk metrics of several sandboxes at once, by id. */
+  metrics(
+    sandboxIds: ReadonlyArray<string>,
+  ): Effect.Effect<sandboxes.SandboxesWithMetrics, E2BError, RuntimeContext>;
+}
+
+/**
+ * Create and manage E2B sandboxes from a Worker, Function or any other host.
+ *
+ * `E2B.CreateSandbox(base)` creates sandboxes from a template or snapshot
+ * declared in the stack; `E2B.CreateSandbox()` takes the template per call.
+ * Both return the same client, whose calls take E2B's own parameters.
+ *
+ * Sandboxes created at run time are tagged with the stack, stage and
+ * binding (`alchemy::stack`, `alchemy::stage`, `alchemy::id` in their E2B
+ * metadata) and are not deleted when the stack is destroyed. List them by
+ * those tags to clean them up:
+ * `sandboxes.list({ metadata: { "alchemy::stack": "my-app", "alchemy::stage": "prod" } })`.
+ * Metadata you pass to `create` merges underneath; it never replaces the
+ * `alchemy::*` keys.
+ *
+ * The host gets its own E2B API key, minted at deploy and revoked when the
+ * host is destroyed. E2B keys are not scoped, so the key reaches the whole
+ * team; it is never the deployer's own.
+ *
+ * ### Creating sandboxes
+ * **Example:** One sandbox per request, killed when the request ends
+ * ```typescript
+ * const sandboxes = yield* E2B.CreateSandbox(Agent);
+ * // in fetch:
+ * const sandbox = yield* Effect.acquireRelease(
+ *   sandboxes.create({ timeout: 120 }),
+ *   (sandbox) => Effect.ignore(sandbox.kill()),
+ * );
+ * const result = yield* sandbox.exec("node --version");
+ * ```
+ *
+ * **Example:** A long-lived sandbox per task, found by metadata
+ * ```typescript
+ * const [existing] = yield* sandboxes.list({ metadata: { task }, state: ["running", "paused"] });
+ * const sandbox = existing
+ *   ? yield* sandboxes.connect(existing.sandboxID)
+ *   : yield* sandboxes.create({ metadata: { task }, autoPause: true, timeout: 1800 });
+ * ```
+ *
+ * ### Running commands
+ * `exec` runs to completion and returns `{ exitCode, stdout, stderr }`; a
+ * non-zero exit is returned, not failed. A string runs in a login shell, an
+ * array runs directly.
+ *
+ * **Example:** A shell line, an argument vector, stdin and a timeout
+ * ```typescript
+ * const test = yield* sandbox.exec("npm test", { cwd: "/home/user/app" });
+ * const version = yield* sandbox.exec(["node", "--version"]);
+ * const sorted = yield* sandbox.exec("sort", { stdin: "b\na\n" });
+ * const slow = yield* sandbox.exec("make", { timeout: "2 minutes" }); // E2B.ExecTimedOut
+ * ```
+ *
+ * **Example:** Stream a process, then wait for it
+ * ```typescript
+ * const build = yield* sandbox.start("npm run build", { cwd: "/home/user/app" });
+ * yield* build.output.pipe(
+ *   Stream.runForEach((chunk) => Effect.log(new TextDecoder().decode(chunk.data))),
+ * );
+ * const { exitCode } = yield* build.wait;
+ * ```
+ *
+ * Closing the scope detaches: the process keeps running, and
+ * `sandbox.processes.attach({ pid })` picks it up again.
+ *
+ * **Example:** A terminal
+ * ```typescript
+ * const pty = yield* sandbox.pty.open({ cols: 120, rows: 40 });
+ * yield* pty.write("ls\n");
+ * yield* pty.resize({ cols: 160, rows: 48 });
+ * ```
+ *
+ * ### Network and secrets
+ * **Example:** Allow only GitHub and inject a token at egress
+ * ```typescript
+ * const github = yield* GitHubToken;
+ * const sandbox = yield* sandboxes.create({
+ *   network: {
+ *     allowOut: ["github.com", "*.github.com"],
+ *     rules: { "api.github.com": [{ transform: { headers: { Authorization: `Bearer ${github.ref}` } } }] },
+ *   },
+ * });
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface CreateSandbox extends Binding.Service<
+  CreateSandbox,
+  "E2B.CreateSandbox",
+  (base?: SandboxBase) => Effect.Effect<SandboxesClient>
+> {}
+
+export const CreateSandbox = Binding.Service<CreateSandbox>("E2B.CreateSandbox");

package/src/CreateSandboxHttp.ts

@@ -0,0 +1,131 @@
+import * as sandboxes from "@distilled.cloud/e2b/sandboxes";
+import type * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { CreateSandbox, type SandboxBase, type SandboxesClient } from "./CreateSandbox.ts";
+import { bindE2B, bindOwnerTags, metadataQuery } from "./E2BBindings.ts";
+import { SandboxBaseMissing } from "./Errors.ts";
+import { denyUnlisted, makeSandboxHandle } from "./internal/SandboxHandle.ts";
+import type { BoundVolumeMount, VolumeMount } from "./MountVolume.ts";
+import type { Template } from "./Template.ts";
+
+/**
+ * HTTP implementation of {@link CreateSandbox}: E2B's control plane with the
+ * team key, and envd inside each sandbox with that sandbox's own token.
+ * Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Cloudflare Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const sandboxes = yield* E2B.CreateSandbox(Agent);
+ *   // ...
+ * }).pipe(Effect.provide(E2B.CreateSandboxHttp))
+ * ```
+ *
+ * @layer
+ * @product Sandbox
+ * @provides E2B.CreateSandbox
+ */
+export const CreateSandboxHttp = Layer.effect(
+  CreateSandbox,
+  Effect.gen(function* () {
+    return Effect.fn("E2B.CreateSandbox")(function* (base?: SandboxBase) {
+      const auth = yield* bindE2B;
+      const owner = yield* bindOwnerTags;
+      // Both a Template and a Snapshot expose the template id sandboxes boot from.
+      const baseId: Effect.Effect<string> | undefined =
+        base === undefined
+          ? undefined
+          : yield* (base.templateId as Output.Output<string, never>).asEffect();
+      // A template program's own mounts (`E2B.MountVolume`) go on every sandbox.
+      const baseMounts: Effect.Effect<ReadonlyArray<VolumeMount>> =
+        base !== undefined && base.Type === "E2B.Template"
+          ? yield* ((base as Template).mounts as Output.Output<VolumeMount[], never>).asEffect()
+          : Effect.succeed([]);
+
+      /** The template's mounts and the call's own, by path (the call's win). */
+      const mountsOf = Effect.fn(function* (
+        mounts: ReadonlyArray<VolumeMount | BoundVolumeMount> | undefined,
+      ) {
+        const byPath = new Map<string, { name: string; path: string }>();
+        for (const mount of yield* baseMounts) {
+          byPath.set(mount.path, { name: mount.volume.name, path: mount.path });
+        }
+        for (const mount of mounts ?? []) {
+          const name =
+            typeof mount.volume.name === "string" ? mount.volume.name : yield* mount.volume.name;
+          byPath.set(mount.path, { name, path: mount.path });
+        }
+        return [...byPath.values()];
+      });
+
+      const withStamp = Effect.fn(function* (
+        metadata: Readonly<Record<string, string | undefined>> | undefined,
+      ) {
+        return { ...metadata, ...(yield* owner) };
+      });
+
+      const client: SandboxesClient = {
+        create: Effect.fn("E2B.CreateSandbox.create")(function* (createOptions) {
+          const templateID =
+            createOptions?.templateID ?? (baseId === undefined ? undefined : yield* baseId);
+          if (templateID === undefined) {
+            return yield* new SandboxBaseMissing({
+              message: "E2B.CreateSandbox() has no bound base: pass `templateID` to create()",
+            });
+          }
+          const domain = yield* auth.domain;
+          const { mounts, ...request } = createOptions ?? {};
+          const volumeMounts = yield* mountsOf(mounts);
+          const created = yield* auth.authorize(
+            sandboxes.createSandbox({
+              ...request,
+              ...(volumeMounts.length === 0 ? {} : { volumeMounts }),
+              ...(createOptions?.network === undefined
+                ? {}
+                : { network: denyUnlisted(createOptions.network) }),
+              templateID,
+              metadata: yield* withStamp(createOptions?.metadata),
+            }),
+          );
+          return makeSandboxHandle(auth, created, domain);
+        }),
+        connect: Effect.fn("E2B.CreateSandbox.connect")(function* (sandboxId, connectOptions) {
+          const domain = yield* auth.domain;
+          const connected = yield* auth.authorize(
+            sandboxes.connectSandbox({ sandboxID: sandboxId, ...connectOptions }),
+          );
+          return makeSandboxHandle(auth, connected, domain);
+        }),
+        get: (sandboxId) => auth.authorize(sandboxes.getSandbox({ sandboxID: sandboxId })),
+        list: Effect.fn("E2B.CreateSandbox.list")(function* (listOptions) {
+          const template =
+            listOptions?.template ?? (baseId === undefined ? undefined : yield* baseId);
+          const all = yield* auth.authorize(
+            Stream.runCollect(
+              sandboxes.listSandboxes.items({
+                ...listOptions,
+                ...(template === undefined ? {} : { template }),
+                metadata:
+                  listOptions?.metadata === undefined
+                    ? undefined
+                    : metadataQuery(listOptions.metadata),
+              }),
+            ),
+          );
+          return Array.from(all);
+        }),
+        kill: (sandboxId) =>
+          auth.authorize(sandboxes.deleteSandbox({ sandboxID: sandboxId })).pipe(
+            Effect.asVoid,
+            Effect.catchTag("NotFound", () => Effect.void),
+          ),
+        metrics: (sandboxIds) =>
+          auth.authorize(sandboxes.listSandboxesMetrics({ sandbox_ids: [...sandboxIds] })),
+      };
+      return client;
+    });
+  }),
+);

package/src/CreateSecret.ts

@@ -0,0 +1,65 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { E2BError } from "./SandboxClient.ts";
+import type { SecretAttributes } from "./Secret.ts";
+
+/** A secret as E2B reports it: never its value. `ref` is the egress placeholder. */
+export type SecretInfo = SecretAttributes;
+
+/** E2B secrets by name: store, look up, list and delete them. */
+export interface SecretsClient {
+  /**
+   * Stores a value under a name: creates the secret, or adds a new version
+   * of an existing one. Returns its `ref` to use in sandbox network rules.
+   */
+  put(
+    name: string,
+    value: Redacted.Redacted<string>,
+    options?: { readonly metadata?: Readonly<Record<string, string>> },
+  ): Effect.Effect<SecretInfo, E2BError, RuntimeContext>;
+  /** The secret with this name or id, or `undefined`. */
+  get(nameOrId: string): Effect.Effect<SecretInfo | undefined, E2BError, RuntimeContext>;
+  /** The secrets this host created. */
+  list(): Effect.Effect<ReadonlyArray<SecretInfo>, E2BError, RuntimeContext>;
+  /** Deletes a secret. Deleting one that is gone succeeds. */
+  delete(nameOrId: string): Effect.Effect<void, E2BError, RuntimeContext>;
+}
+
+/**
+ * Store per-user credentials as E2B secrets at runtime, and reference them
+ * from a sandbox's network rules so the sandbox never sees the value.
+ *
+ * Secrets created at run time are tagged with the stack, stage and binding
+ * (`alchemy::stack`, `alchemy::stage`, `alchemy::id` in their E2B metadata)
+ * and are not deleted when the stack is destroyed. List them by those tags
+ * to clean them up: `secrets.list()` returns the ones this binding stored.
+ * Metadata you pass to `put` merges underneath; it never replaces the
+ * `alchemy::*` keys.
+ *
+ * ### Per-user credentials at egress
+ * **Example:** A user's GitHub token, injected into their sandbox's GitHub calls
+ * ```typescript
+ * const secrets = yield* E2B.CreateSecret();
+ * const sandboxes = yield* E2B.CreateSandbox(Agent);
+ * // in fetch:
+ * const github = yield* secrets.put(`github-${user}`, Redacted.make(token));
+ * const sandbox = yield* sandboxes.create({
+ *   network: {
+ *     allowOut: ["api.github.com"],
+ *     rules: { "api.github.com": [{ transform: { headers: { Authorization: `Bearer ${github.ref}` } } }] },
+ *   },
+ * });
+ * ```
+ *
+ * @binding
+ * @product Secret
+ */
+export interface CreateSecret extends Binding.Service<
+  CreateSecret,
+  "E2B.CreateSecret",
+  () => Effect.Effect<SecretsClient>
+> {}
+
+export const CreateSecret = Binding.Service<CreateSecret>("E2B.CreateSecret");

package/src/CreateSecretHttp.ts

@@ -0,0 +1,94 @@
+import * as secrets from "@distilled.cloud/e2b/secrets";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { CreateSecret, type SecretsClient } from "./CreateSecret.ts";
+import { bindE2B, bindOwnerTags } from "./E2BBindings.ts";
+import { E2BUnexpectedResponse } from "./Errors.ts";
+import { toSecretAttributes } from "./Secret.ts";
+
+/**
+ * HTTP implementation of {@link CreateSecret}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const secrets = yield* E2B.CreateSecret();
+ *   // ...
+ * }).pipe(Effect.provide(E2B.CreateSecretHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret
+ * @provides E2B.CreateSecret
+ */
+export const CreateSecretHttp = Layer.effect(
+  CreateSecret,
+  Effect.gen(function* () {
+    return Effect.fn("E2B.CreateSecret")(function* () {
+      const auth = yield* bindE2B;
+      const owner = yield* bindOwnerTags;
+
+      const get = (nameOrId: string) =>
+        auth.authorize(secrets.getSecret({ secretID: nameOrId.toLowerCase() })).pipe(
+          Effect.map((secret): secrets.Secret | undefined => secret),
+          Effect.catchTag("NotFound", () => Effect.undefined),
+        );
+
+      const client: SecretsClient = {
+        put: Effect.fn("E2B.CreateSecret.put")(function* (name, value, putOptions) {
+          const metadata = { ...putOptions?.metadata, ...(yield* owner) };
+          const existing = yield* get(name);
+          const stored =
+            existing !== undefined
+              ? yield* auth.authorize(
+                  secrets.updateSecret({ secretID: existing.secretID, value, metadata }),
+                )
+              : yield* auth.authorize(secrets.createSecret({ name, value, metadata })).pipe(
+                  // A concurrent put created it first: add our version.
+                  Effect.catchTag("Conflict", () =>
+                    Effect.gen(function* () {
+                      const raced = yield* get(name);
+                      if (raced === undefined) {
+                        return yield* new E2BUnexpectedResponse({
+                          message: `E2B secret ${name} vanished during put`,
+                        });
+                      }
+                      return yield* auth.authorize(
+                        secrets.updateSecret({ secretID: raced.secretID, value, metadata }),
+                      );
+                    }),
+                  ),
+                );
+          return toSecretAttributes(stored);
+        }),
+        get: (nameOrId) =>
+          get(nameOrId).pipe(
+            Effect.map((secret) => (secret === undefined ? undefined : toSecretAttributes(secret))),
+          ),
+        list: Effect.fn("E2B.CreateSecret.list")(function* () {
+          const owned = yield* owner;
+          const all = yield* auth.authorize(
+            Stream.runCollect(secrets.listSecrets.items({ limit: 100 })),
+          );
+          return Array.from(all)
+            .filter((secret) =>
+              Object.entries(owned).every(([key, value]) => secret.metadata[key] === value),
+            )
+            .map(toSecretAttributes);
+        }),
+        delete: (nameOrId) =>
+          Effect.flatMap(get(nameOrId), (secret) =>
+            secret === undefined
+              ? Effect.void
+              : auth.authorize(secrets.deleteSecret({ secretID: secret.secretID })).pipe(
+                  Effect.asVoid,
+                  Effect.catchTag("NotFound", () => Effect.void),
+                ),
+          ),
+      };
+      return client;
+    });
+  }),
+);

package/src/CreateSnapshot.ts

@@ -0,0 +1,64 @@
+import type * as sandboxes from "@distilled.cloud/e2b/sandboxes";
+import type * as snapshots from "@distilled.cloud/e2b/snapshots";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { SnapshotSetupFailed } from "./Errors.ts";
+import type { SnapshotSetup } from "./internal/SnapshotBuild.ts";
+import type { E2BError } from "./SandboxClient.ts";
+
+export type { SnapshotSetup } from "./internal/SnapshotBuild.ts";
+
+/** E2B snapshots: take, list and delete them at runtime. */
+export interface SnapshotsClient {
+  /**
+   * Boots `template`, runs the setup commands, snapshots it under `name` and
+   * kills the setup sandbox. Snapshotting under an existing name adds a new
+   * version. Use `sandbox.snapshot()` to snapshot a sandbox you already have.
+   */
+  create(
+    name: string,
+    setup: SnapshotSetup,
+  ): Effect.Effect<sandboxes.SnapshotInfo, E2BError | SnapshotSetupFailed, RuntimeContext>;
+  /** Snapshots, filtered by source sandbox or name. */
+  list(
+    options?: Omit<snapshots.ListSnapshotsRequest, "nextToken">,
+  ): Effect.Effect<ReadonlyArray<snapshots.SnapshotInfo>, E2BError, RuntimeContext>;
+  /** Deletes a snapshot (and every version of it). Deleting one that is gone succeeds. */
+  delete(name: string): Effect.Effect<void, E2BError, RuntimeContext>;
+}
+
+/**
+ * Take and manage E2B snapshots at runtime: a warm base per repository or
+ * per customer, created on demand and forked into sandboxes.
+ *
+ * Snapshots taken at runtime carry no metadata, so they are not deleted when
+ * the host is destroyed. Delete them with `delete` when their owner goes
+ * away.
+ *
+ * ### Warm bases at runtime
+ * **Example:** A warm base per repository
+ * ```typescript
+ * const snapshots = yield* E2B.CreateSnapshot();
+ * const sandboxes = yield* E2B.CreateSandbox();
+ * // in fetch:
+ * const [existing] = yield* snapshots.list({ name: `warm-${slug}` });
+ * const base =
+ *   existing ??
+ *   (yield* snapshots.create(`warm-${slug}`, {
+ *     template: "node-22",
+ *     run: [`git clone https://github.com/${repo} repo`, "cd repo && npm ci"],
+ *   }));
+ * const sandbox = yield* sandboxes.create({ templateID: base.snapshotID });
+ * ```
+ *
+ * @binding
+ * @product Snapshot
+ */
+export interface CreateSnapshot extends Binding.Service<
+  CreateSnapshot,
+  "E2B.CreateSnapshot",
+  () => Effect.Effect<SnapshotsClient>
+> {}
+
+export const CreateSnapshot = Binding.Service<CreateSnapshot>("E2B.CreateSnapshot");

package/src/CreateSnapshotHttp.ts

@@ -0,0 +1,55 @@
+import * as snapshots from "@distilled.cloud/e2b/snapshots";
+import * as templates from "@distilled.cloud/e2b/templates";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { CreateSnapshot, type SnapshotsClient } from "./CreateSnapshot.ts";
+import { bindE2B } from "./E2BBindings.ts";
+import { takeSnapshot } from "./internal/SnapshotBuild.ts";
+
+/**
+ * HTTP implementation of {@link CreateSnapshot}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const snapshots = yield* E2B.CreateSnapshot();
+ *   // ...
+ * }).pipe(Effect.provide(E2B.CreateSnapshotHttp))
+ * ```
+ *
+ * @layer
+ * @product Snapshot
+ * @provides E2B.CreateSnapshot
+ */
+export const CreateSnapshotHttp = Layer.succeed(
+  CreateSnapshot,
+  Effect.fn("E2B.CreateSnapshot")(function* () {
+    const auth = yield* bindE2B;
+    const client: SnapshotsClient = {
+      create: (name, setup) => auth.authorize(takeSnapshot(name, setup)),
+      list: (options) =>
+        auth
+          .authorize(Stream.runCollect(snapshots.listSnapshots.items({ ...options })))
+          .pipe(Effect.map((all) => Array.from(all))),
+      // A snapshot is stored as a template under its name.
+      delete: (name) =>
+        auth
+          .authorize(
+            templates
+              .getTemplateByAlias({ alias: name })
+              .pipe(
+                Effect.flatMap((alias) =>
+                  templates.deleteTemplate({ templateID: alias.templateID }),
+                ),
+              ),
+          )
+          .pipe(
+            Effect.asVoid,
+            Effect.catchTag("NotFound", () => Effect.void),
+          ),
+    };
+    return client;
+  }),
+);