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

package/src/CreateTemplate.ts

@@ -0,0 +1,135 @@
+import type * as tags from "@distilled.cloud/e2b/tags";
+import type * as templates from "@distilled.cloud/e2b/templates";
+import type * as unstable from "@distilled.cloud/e2b/unstable";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type * as PlatformError from "effect/PlatformError";
+import type { TemplateBuildFailed } from "./Errors.ts";
+import type { TemplateBuildSpec } from "./internal/TemplateBuild.ts";
+import type { E2BError } from "./SandboxClient.ts";
+
+/**
+ * What a runtime build takes: E2B's own build inputs (a base `image` or
+ * `fromTemplate`, then `env`, `files` and `run` steps), with no Dockerfile.
+ * Files come from memory; there is no build-context directory where a
+ * Worker runs.
+ */
+export type RuntimeTemplateSpec = TemplateBuildSpec;
+
+/** A built template. */
+export interface TemplateInfo {
+  readonly templateId: string;
+  readonly buildId: string;
+  /** Fully qualified names, e.g. `my-team/my-template:default`. */
+  readonly names: ReadonlyArray<string>;
+}
+
+/** Errors a runtime build can fail with. */
+export type TemplateBuildError = E2BError | TemplateBuildFailed | PlatformError.PlatformError;
+
+/** E2B templates: build, look up, tag and delete them at runtime. */
+export interface TemplatesClient {
+  /** Builds a template and waits until it is ready. */
+  build(spec: RuntimeTemplateSpec): Effect.Effect<TemplateInfo, TemplateBuildError, RuntimeContext>;
+  /**
+   * Builds a template unless a ready build of these exact inputs exists.
+   * Each build is tagged with its content hash, so a repeat call is one
+   * lookup.
+   */
+  getOrBuild(
+    spec: RuntimeTemplateSpec,
+  ): Effect.Effect<TemplateInfo, TemplateBuildError, RuntimeContext>;
+  /** A template by id or name (alias), or `undefined`. */
+  get(
+    nameOrId: string,
+  ): Effect.Effect<templates.GetTemplateResponse | undefined, E2BError, RuntimeContext>;
+  /** The team's templates. */
+  list(
+    options?: Omit<templates.ListTemplatesRequest, "teamID" | "nextToken">,
+  ): Effect.Effect<ReadonlyArray<templates.Template>, E2BError, RuntimeContext>;
+  /** E2B's public base templates. */
+  listDefaults(): Effect.Effect<templates.ListDefaultTemplatesResponse, E2BError, RuntimeContext>;
+  /** Templates matching a search. */
+  search(
+    options: unstable.SearchTemplatesRequest,
+  ): Effect.Effect<unstable.TemplateSearchResponse, E2BError, RuntimeContext>;
+  /** Whether other teams can create sandboxes from the template. */
+  setPublic(templateId: string, isPublic: boolean): Effect.Effect<void, E2BError, RuntimeContext>;
+  /** A build's status, with its newest log lines. */
+  buildStatus(
+    templateId: string,
+    buildId: string,
+    options?: Omit<templates.GetTemplateBuildStatusRequest, "templateID" | "buildID">,
+  ): Effect.Effect<templates.TemplateBuildInfo, E2BError, RuntimeContext>;
+  /** A build's logs. */
+  buildLogs(
+    templateId: string,
+    buildId: string,
+    options?: Omit<templates.ListTemplateBuildLogsRequest, "templateID" | "buildID">,
+  ): Effect.Effect<templates.TemplateBuildLogsResponse, E2BError, RuntimeContext>;
+  /** Deletes a template. Deleting one that is gone succeeds. */
+  delete(templateId: string): Effect.Effect<void, E2BError, RuntimeContext>;
+  /** Tags on builds: `name:tag` names a build sandboxes are created from. */
+  readonly tags: {
+    /** Assigns tags to the build `target` (`name:tag` or `name`) points at. */
+    assign(
+      target: string,
+      tags: ReadonlyArray<string>,
+    ): Effect.Effect<tags.AssignedTemplateTags, E2BError, RuntimeContext>;
+    /** Removes tags from a template by name. */
+    remove(
+      name: string,
+      tags: ReadonlyArray<string>,
+    ): Effect.Effect<void, E2BError, RuntimeContext>;
+    list(
+      templateId: string,
+    ): Effect.Effect<tags.ListTemplateTagsResponse, E2BError, RuntimeContext>;
+    exists(templateId: string, tag: string): Effect.Effect<boolean, E2BError, RuntimeContext>;
+    count(templateId: string): Effect.Effect<number, E2BError, RuntimeContext>;
+    groups(
+      templateId: string,
+      options?: Omit<tags.ListTemplateTagGroupsRequest, "templateID">,
+    ): Effect.Effect<tags.TemplateTagGroupsResponse, E2BError, RuntimeContext>;
+    assignments(
+      templateId: string,
+      tag: string,
+      options?: Omit<tags.ListTemplateTagAssignmentsRequest, "templateID" | "tag">,
+    ): Effect.Effect<tags.TemplateTagAssignmentsResponse, E2BError, RuntimeContext>;
+  };
+}
+
+/**
+ * Build E2B templates at runtime from E2B's own build inputs: a template
+ * per repository, per customer image, per agent configuration.
+ * E2B builds remotely, so this works from a Worker.
+ *
+ * Templates built at runtime carry no metadata, so they are not deleted
+ * when the host is destroyed. Delete them with `delete` when their owner
+ * goes away.
+ *
+ * ### Building at runtime
+ * **Example:** A template per repository, built once
+ * ```typescript
+ * const templates = yield* E2B.CreateTemplate();
+ * const sandboxes = yield* E2B.CreateSandbox();
+ * // in fetch:
+ * const template = yield* templates.getOrBuild({
+ *   name: `repo-${slug}`,
+ *   image: "node:22-bookworm",
+ *   files: [{ path: "/home/user/app/package.json", contents: packageJson }],
+ *   run: ["cd /home/user/app && npm install"],
+ * });
+ * const sandbox = yield* sandboxes.create({ templateID: template.templateId });
+ * ```
+ *
+ * @binding
+ * @product Template
+ */
+export interface CreateTemplate extends Binding.Service<
+  CreateTemplate,
+  "E2B.CreateTemplate",
+  () => Effect.Effect<TemplatesClient>
+> {}
+
+export const CreateTemplate = Binding.Service<CreateTemplate>("E2B.CreateTemplate");

package/src/CreateTemplateHttp.ts

@@ -0,0 +1,152 @@
+import * as tags from "@distilled.cloud/e2b/tags";
+import * as templates from "@distilled.cloud/e2b/templates";
+import * as unstable from "@distilled.cloud/e2b/unstable";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import {
+  CreateTemplate,
+  type RuntimeTemplateSpec,
+  type TemplateInfo,
+  type TemplatesClient,
+} from "./CreateTemplate.ts";
+import { bindE2B } from "./E2BBindings.ts";
+import { planTemplateBuild, runTemplateBuild } from "./internal/TemplateBuild.ts";
+
+/** The tag a build of these inputs carries. */
+const hashTag = (hash: string) => `alchemy-${hash.slice(0, 16)}`;
+
+/**
+ * HTTP implementation of {@link CreateTemplate}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const templates = yield* E2B.CreateTemplate();
+ *   // ...
+ * }).pipe(Effect.provide(E2B.CreateTemplateHttp))
+ * ```
+ *
+ * @layer
+ * @product Template
+ * @provides E2B.CreateTemplate
+ */
+export const CreateTemplateHttp = Layer.succeed(
+  CreateTemplate,
+  Effect.fn("E2B.CreateTemplate")(function* () {
+    const auth = yield* bindE2B;
+
+    const get = (nameOrId: string) =>
+      auth
+        .authorize(
+          templates
+            .getTemplate({ templateID: nameOrId })
+            .pipe(
+              Effect.catchTag("NotFound", () =>
+                templates
+                  .getTemplateByAlias({ alias: nameOrId })
+                  .pipe(
+                    Effect.flatMap((alias) =>
+                      templates.getTemplate({ templateID: alias.templateID }),
+                    ),
+                  ),
+              ),
+            ),
+        )
+        .pipe(
+          Effect.map((template): templates.GetTemplateResponse | undefined => template),
+          Effect.catchTag("NotFound", () => Effect.undefined),
+        );
+
+    const build = Effect.fn("E2B.CreateTemplate.build")(function* (spec: RuntimeTemplateSpec) {
+      const plan = yield* planTemplateBuild(spec);
+      const built = yield* auth.authorize(
+        // E2B builds the `default` tag only when no tags are given, so keep it
+        // next to the hash tag unless the caller chose its own.
+        runTemplateBuild(
+          { ...spec, tags: [...(spec.tags ?? ["default"]), hashTag(plan.hash)] },
+          plan,
+        ),
+      );
+      return {
+        templateId: built.templateId,
+        buildId: built.buildId,
+        names: built.names,
+      } satisfies TemplateInfo;
+    });
+
+    const client: TemplatesClient = {
+      build,
+      getOrBuild: Effect.fn("E2B.CreateTemplate.getOrBuild")(function* (spec) {
+        const plan = yield* planTemplateBuild(spec);
+        const existing = yield* get(spec.name);
+        if (existing !== undefined) {
+          const tagged = yield* auth.authorize(
+            tags.getTemplateTagExists({ templateID: existing.templateID, tag: hashTag(plan.hash) }),
+          );
+          const ready =
+            existing.builds.find((b) => b.buildID === existing.buildID)?.status === "ready";
+          if (tagged.exists && ready) {
+            return {
+              templateId: existing.templateID,
+              buildId: existing.buildID,
+              names: existing.names,
+            };
+          }
+        }
+        return yield* build(spec);
+      }),
+      get,
+      list: (options) =>
+        auth
+          .authorize(Stream.runCollect(templates.listTemplates.items({ ...options })))
+          .pipe(Effect.map((all) => Array.from(all))),
+      listDefaults: () => auth.authorize(templates.listDefaultTemplates({})),
+      search: (options) => auth.authorize(unstable.searchTemplates(options)),
+      setPublic: (templateId, isPublic) =>
+        auth
+          .authorize(templates.updateTemplate({ templateID: templateId, public: isPublic }))
+          .pipe(Effect.asVoid),
+      buildStatus: (templateId, buildId, options) =>
+        auth.authorize(
+          templates.getTemplateBuildStatus({
+            ...options,
+            templateID: templateId,
+            buildID: buildId,
+          }),
+        ),
+      buildLogs: (templateId, buildId, options) =>
+        auth.authorize(
+          templates.listTemplateBuildLogs({ ...options, templateID: templateId, buildID: buildId }),
+        ),
+      delete: (templateId) =>
+        auth.authorize(templates.deleteTemplate({ templateID: templateId })).pipe(
+          Effect.asVoid,
+          Effect.catchTag("NotFound", () => Effect.void),
+        ),
+      tags: {
+        assign: (target, assigned) =>
+          auth.authorize(tags.createTemplateTag({ target, tags: [...assigned] })),
+        remove: (name, removed) =>
+          auth.authorize(tags.deleteTemplateTags({ name, tags: [...removed] })).pipe(Effect.asVoid),
+        list: (templateId) => auth.authorize(tags.listTemplateTags({ templateID: templateId })),
+        exists: (templateId, tag) =>
+          auth
+            .authorize(tags.getTemplateTagExists({ templateID: templateId, tag }))
+            .pipe(Effect.map((res) => res.exists)),
+        count: (templateId) =>
+          auth
+            .authorize(tags.getTemplateTagCount({ templateID: templateId }))
+            .pipe(Effect.map((res) => res.total)),
+        groups: (templateId, options) =>
+          auth.authorize(tags.listTemplateTagGroups({ ...options, templateID: templateId })),
+        assignments: (templateId, tag, options) =>
+          auth.authorize(
+            tags.listTemplateTagAssignments({ ...options, templateID: templateId, tag }),
+          ),
+      },
+    };
+    return client;
+  }),
+);

package/src/CreateVolume.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 { E2BError } from "./SandboxClient.ts";
+import type { ReadWriteVolumeClient } from "./VolumeFiles.ts";
+
+/** A volume created or found at runtime, with its files. */
+export interface VolumeHandle {
+  /** E2B's volume id. */
+  readonly volumeId: string;
+  /** The volume's name. Mount it with `mounts: [{ volume, path }]`. */
+  readonly name: string;
+  /** The volume's files, readable and writable without a sandbox. */
+  readonly files: ReadWriteVolumeClient;
+}
+
+/** E2B volumes by name: create, look up, list and delete them. */
+export interface VolumesClient {
+  /** Creates a volume. Fails with `Conflict` when the name is taken. */
+  create(name: string): Effect.Effect<VolumeHandle, E2BError, RuntimeContext>;
+  /** The volume with this name or id, or `undefined`. */
+  get(nameOrId: string): Effect.Effect<VolumeHandle | undefined, E2BError, RuntimeContext>;
+  /** The volume with this name, created if missing. Safe to race. */
+  getOrCreate(name: string): Effect.Effect<VolumeHandle, E2BError, RuntimeContext>;
+  /** Every volume in the team. */
+  list(): Effect.Effect<
+    ReadonlyArray<{ readonly volumeId: string; readonly name: string }>,
+    E2BError,
+    RuntimeContext
+  >;
+  /** Deletes a volume and its files. Deleting one that is gone succeeds. */
+  delete(volumeId: string): Effect.Effect<void, E2BError, RuntimeContext>;
+}
+
+/**
+ * Create and manage E2B volumes at runtime, by name: a home directory per
+ * user, a workspace per session. Mount one into a sandbox by its `name`, and
+ * read or write its files with `files` without a sandbox.
+ *
+ * E2B volumes carry no metadata, so the volumes a host creates at runtime
+ * are not deleted when the host is destroyed. Delete them with `delete` when
+ * their owner goes away.
+ *
+ * ### Per-user volumes
+ * **Example:** A home volume per user, mounted into their sandbox
+ * ```typescript
+ * const volumes = yield* E2B.CreateVolume();
+ * const sandboxes = yield* E2B.CreateSandbox(Agent);
+ * // in fetch:
+ * const home = yield* volumes.getOrCreate(`user-${user}`);
+ * const sandbox = yield* sandboxes.create({
+ *   mounts: [{ volume: home, path: "/home/user/work" }],
+ * });
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface CreateVolume extends Binding.Service<
+  CreateVolume,
+  "E2B.CreateVolume",
+  () => Effect.Effect<VolumesClient>
+> {}
+
+export const CreateVolume = Binding.Service<CreateVolume>("E2B.CreateVolume");

package/src/CreateVolumeHttp.ts

@@ -0,0 +1,80 @@
+import * as volumes from "@distilled.cloud/e2b/volumes";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { CreateVolume, type VolumeHandle, type VolumesClient } from "./CreateVolume.ts";
+import { bindE2B, type E2BAuth } from "./E2BBindings.ts";
+import { makeVolumeFiles } from "./internal/VolumeHttp.ts";
+
+const handleOf = (auth: E2BAuth, volume: { volumeID: string; name: string }): VolumeHandle => ({
+  volumeId: volume.volumeID,
+  name: volume.name,
+  files: makeVolumeFiles(auth, Effect.succeed(volume.volumeID)),
+});
+
+/**
+ * HTTP implementation of {@link CreateVolume}. Works on any host.
+ *
+ * ### Provide the layer
+ * **Example:** On a Worker
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const volumes = yield* E2B.CreateVolume();
+ *   // ...
+ * }).pipe(Effect.provide(E2B.CreateVolumeHttp))
+ * ```
+ *
+ * @layer
+ * @product Volume
+ * @provides E2B.CreateVolume
+ */
+export const CreateVolumeHttp = Layer.succeed(
+  CreateVolume,
+  Effect.fn("E2B.CreateVolume")(function* () {
+    const auth = yield* bindE2B;
+    const findByName = (name: string) =>
+      auth
+        .authorize(volumes.listVolumes({}))
+        .pipe(Effect.map((all) => all.find((volume) => volume.name === name)));
+    const get = (nameOrId: string) =>
+      auth.authorize(volumes.getVolume({ volumeID: nameOrId })).pipe(
+        Effect.map((volume): { volumeID: string; name: string } | undefined => volume),
+        Effect.catchTag("NotFound", () => findByName(nameOrId)),
+        Effect.map((volume) => (volume === undefined ? undefined : handleOf(auth, volume))),
+      );
+    const client: VolumesClient = {
+      create: (name) =>
+        auth
+          .authorize(volumes.createVolume({ name }))
+          .pipe(Effect.map((volume) => handleOf(auth, volume))),
+      get,
+      getOrCreate: (name) =>
+        Effect.flatMap(get(name), (existing) =>
+          existing !== undefined
+            ? Effect.succeed(existing)
+            : auth.authorize(volumes.createVolume({ name })).pipe(
+                Effect.map((volume) => handleOf(auth, volume)),
+                // A concurrent create won the name: use theirs.
+                Effect.catchTag("Conflict", (error) =>
+                  Effect.flatMap(get(name), (raced) =>
+                    raced === undefined ? Effect.fail(error) : Effect.succeed(raced),
+                  ),
+                ),
+              ),
+        ),
+      list: () =>
+        auth
+          .authorize(volumes.listVolumes({}))
+          .pipe(
+            Effect.map((all) =>
+              all.map((volume) => ({ volumeId: volume.volumeID, name: volume.name })),
+            ),
+          ),
+      delete: (volumeId) =>
+        auth.authorize(volumes.deleteVolume({ volumeID: volumeId })).pipe(
+          Effect.asVoid,
+          Effect.catchTag("NotFound", () => Effect.void),
+        ),
+    };
+    return client;
+  }),
+);

package/src/Credentials.ts

@@ -0,0 +1,81 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import * as auth from "@distilled.cloud/e2b/auth";
+import {
+  apiBaseUrlFor,
+  Credentials,
+  credentials,
+  type Config,
+} from "@distilled.cloud/e2b/Credentials";
+import { lazyCredentials } from "alchemy/Auth/Resolve";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { E2B_AUTH_PROVIDER_NAME, type E2BResolvedCredentials } from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  credentials,
+  DEFAULT_DOMAIN,
+  type Config as CredentialsConfig,
+} from "@distilled.cloud/e2b/Credentials";
+
+/**
+ * Fills in the team id for an access token that came without one: E2B
+ * lists the token's teams, and the default team is the one it acts on.
+ */
+export const withTeamId = Effect.fn(function* (config: Config) {
+  if (config.accessToken === undefined || (config.teamId ?? "") !== "") return config;
+  const teams = yield* auth.listTeams({}).pipe(
+    Effect.provide(Layer.mergeAll(credentials(config), FetchHttpClient.layer)),
+    Effect.mapError(
+      (cause) =>
+        new ConfigError({
+          message: `Failed to look up the E2B team for the access token: ${cause.message}`,
+        }),
+    ),
+  );
+  const team = teams.find((t) => t.isDefault) ?? (teams.length === 1 ? teams[0] : undefined);
+  if (team === undefined) {
+    return yield* new ConfigError({
+      message:
+        teams.length === 0
+          ? "The E2B access token belongs to no team"
+          : `The E2B access token belongs to ${teams.length} teams and none is the default: set teamId (E2B_TEAM_ID)`,
+    });
+  }
+  return { ...config, teamId: team.teamID };
+});
+
+/**
+ * Build a `Credentials` layer that resolves E2B credentials via the current
+ * Alchemy profile, or directly from environment variables in CI. An access
+ * token without a team id gets its default team's id. A browser login's
+ * token is re-resolved (and refreshed) before it expires.
+ */
+export const fromAuthProvider = () =>
+  Layer.effect(
+    Credentials,
+    Effect.gen(function* () {
+      const resolve = yield* lazyCredentials<E2BResolvedCredentials, ConfigError>()(
+        E2B_AUTH_PROVIDER_NAME,
+        (creds): Config => ({
+          ...(creds.apiKey === undefined ? {} : { apiKey: creds.apiKey }),
+          ...(creds.accessToken === undefined ? {} : { accessToken: creds.accessToken }),
+          ...(creds.teamId === undefined ? {} : { teamId: creds.teamId }),
+          domain: creds.domain,
+          apiBaseUrl: apiBaseUrlFor(creds.domain),
+        }),
+        { expiresAt: (creds) => creds.expires },
+      );
+      // The team lookup runs once; a failed one is retried on the next call.
+      let teamId: string | undefined;
+      return Effect.gen(function* () {
+        const config = yield* resolve;
+        if (teamId !== undefined && (config.teamId ?? "") === "") return { ...config, teamId };
+        const withTeam = yield* withTeamId(config);
+        teamId = withTeam.teamId;
+        return withTeam;
+      });
+    }),
+  );

package/src/E2BBindings.ts

@@ -0,0 +1,160 @@
+/**
+ * How E2B bindings reach E2B from any host.
+ *
+ * E2B authenticates with a team API key and has no identity federation or
+ * key scopes, so every host — a Cloudflare Worker, a Lambda, a container, an
+ * E2B sandbox — gets its own API key, minted at deploy as an `E2B.ApiKey` in
+ * the host's namespace and deleted with the host. The deployer's credentials
+ * never reach a host. Minting takes the deployer's access token. The binding
+ * captures the key (and the E2B domain) as named runtime Outputs; inside the
+ * deployed host they are read back from the host's env, still `Redacted`.
+ * Every runtime call provides `Credentials` from those accessors, so nothing
+ * reads `process.env`.
+ *
+ * Bindings that create sandboxes or secrets at run time tag them with the
+ * host's `alchemy::stack` / `alchemy::stage` / `alchemy::id`, computed at
+ * deploy and bound into the host (`bindOwnerTags`). Destroying the stack
+ * does not delete them.
+ */
+import { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  apiBaseUrlFor,
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_DOMAIN,
+} from "@distilled.cloud/e2b/Credentials";
+import { orDieCredentialsUnavailable } from "alchemy/Auth/Resolve";
+import * as Binding from "alchemy/Binding";
+import * as Namespace from "alchemy/Namespace";
+import * as Output from "alchemy/Output";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import { ApiKey } from "./ApiKey.ts";
+import { withTeamId } from "./Credentials.ts";
+
+/** A plain value as an Output with no requirements (`asOutput` leaves them `any`). */
+const output = <A>(value: A) => Output.asOutput(value) as Output.Output<A, never>;
+
+/** The `alchemy::*` metadata on objects a host creates at run time. */
+export type OwnerTags = Readonly<Record<string, string>>;
+
+/** E2B's `metadata` filter: `key=value&…`. */
+export const metadataQuery = (metadata: Readonly<Record<string, string>>) =>
+  new URLSearchParams(Object.entries(metadata)).toString();
+
+export interface E2BAuth {
+  /** Runs a distilled call with the bound credentials and an HTTP client. */
+  readonly authorize: <A, E>(
+    effect: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ) => Effect.Effect<A, E, RuntimeContext>;
+  /** The E2B domain sandboxes are addressed under. */
+  readonly domain: Effect.Effect<string>;
+  /** The team the host's key belongs to. */
+  readonly teamId: Effect.Effect<string>;
+}
+
+/** The deploying stack's credentials: the ambient profile-backed ones, else the env. */
+const deployCredentials = Effect.gen(function* () {
+  const ambient = yield* Effect.serviceOption(Credentials);
+  const resolve = Option.isSome(ambient)
+    ? ambient.value
+    : yield* Credentials.pipe(Effect.provide(CredentialsFromEnv));
+  return yield* resolve;
+});
+
+const requireAccessToken = (config: { readonly accessToken?: Redacted.Redacted<string> }) =>
+  config.accessToken === undefined
+    ? Effect.fail(
+        new ConfigError({
+          message:
+            "E2B bindings mint an API key for each host, which takes an E2B access token: " +
+            "add accessToken to the E2B profile (alchemy profile edit --add E2B) or set E2B_ACCESS_TOKEN",
+        }),
+      )
+    : Effect.void;
+
+/**
+ * Mints the current host's API key and binds it, the domain and the
+ * ownership stamp onto the host, and returns runtime accessors for them.
+ * Call it in a binding's construction; every binding on a host shares the
+ * one key.
+ */
+export const bindE2B = Effect.gen(function* () {
+  // Yielding the resource class erases its `Providers` requirement; the
+  // stack satisfies it at plan time.
+  const makeKey = yield* ApiKey;
+  let apiKey: Output.Output<Redacted.Redacted<string>, never> = output(Redacted.make(""));
+  let domain = DEFAULT_DOMAIN;
+  let teamId = "";
+  if (!globalThis.__ALCHEMY_RUNTIME__) {
+    const config = yield* deployCredentials.pipe(orDieCredentialsUnavailable("E2B"));
+    yield* requireAccessToken(config).pipe(orDieCredentialsUnavailable("E2B"));
+    domain = config.domain;
+    teamId = (yield* withTeamId(config).pipe(orDieCredentialsUnavailable("E2B"))).teamId ?? "";
+    const host = yield* Binding.Host;
+    if (host !== undefined) {
+      const hostKey = yield* Namespace.push(host.LogicalId, makeKey("E2BHostKey", {}));
+      apiKey = hostKey.key as Output.Output<Redacted.Redacted<string>, never>;
+    }
+  }
+  const key = yield* Output.named(apiKey, "E2B_API_KEY").asEffect();
+  const boundDomain = yield* Output.named(output(domain), "E2B_DOMAIN").asEffect();
+  const boundTeamId = yield* Output.named(output(teamId), "E2B_TEAM_ID").asEffect();
+
+  const domainOf = Effect.map(boundDomain, (value) => value || DEFAULT_DOMAIN);
+  const credentials = Effect.gen(function* () {
+    const resolvedDomain = yield* domainOf;
+    return {
+      apiKey: yield* key,
+      domain: resolvedDomain,
+      apiBaseUrl: apiBaseUrlFor(resolvedDomain),
+    };
+  });
+  const services = Layer.mergeAll(Layer.succeed(Credentials, credentials), FetchHttpClient.layer);
+
+  return {
+    authorize: (effect) => effect.pipe(Effect.provide(services)),
+    domain: domainOf,
+    teamId: boundTeamId,
+  } satisfies E2BAuth;
+});
+
+const parseOwnerTags = (json: string): OwnerTags => {
+  try {
+    return JSON.parse(json || "{}");
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * Binds the host's `alchemy::stack` / `alchemy::stage` / `alchemy::id` into
+ * it, and returns them at run time for `create` to put on what it makes.
+ * Without a host (a script) there are none.
+ */
+export const bindOwnerTags = Effect.gen(function* () {
+  let tags = "{}";
+  if (!globalThis.__ALCHEMY_RUNTIME__) {
+    const host = yield* Binding.Host;
+    // The values `createInternalTags(host.LogicalId)` gives, read without
+    // adding `Stack` / `Stage` to the binding's requirements.
+    const stack = yield* Effect.serviceOption(Stack);
+    const stage = yield* Effect.serviceOption(Stage);
+    if (host !== undefined && Option.isSome(stack) && Option.isSome(stage)) {
+      tags = JSON.stringify({
+        "alchemy::stack": stack.value.name,
+        "alchemy::stage": stage.value,
+        "alchemy::id": host.LogicalId,
+      } satisfies OwnerTags);
+    }
+  }
+  const bound = yield* Output.named(output(tags), "E2B_OWNER_TAGS").asEffect();
+  return Effect.map(bound, parseOwnerTags);
+});