feat(ai): coding-agent harnesses — Claude Code, Codex, OpenCode, ACP

[sam-goodwin]

Coding-agent harnesses in sandboxes. A sandbox holds no credentials: its requests to GitHub, Anthropic and other egress hosts go through an egress gateway that checks them and adds the real credential.

Declare a sandbox

// src/Sandbox.ts
import * as AI from "alchemy/AI";
import * as Anthropic from "alchemy/Anthropic";
import * as GitHub from "alchemy/GitHub";

export class Sandbox extends AI.Sandbox<
  Sandbox,
  {
    size: "small" | "large";
    egress: GitHub.Egress | Anthropic.Egress;
  }
>()("Sandbox", { egress: [GitHub.Egress, Anthropic.Egress] }) {}

Host it on Cloudflare

// src/Sandbox.cloudflare.ts
import * as Anthropic from "alchemy/Anthropic";
import * as Cloudflare from "alchemy/Cloudflare";
import { Sandbox } from "./Sandbox.ts";

export default Cloudflare.Containers.Sandbox(
  Sandbox,
  {
    main: import.meta.url,
    runtime: "node",
    image: "node:24-bookworm",
    sizes: { small: "lite", large: "standard-4" }, // instance type, chosen at start()
  },
  Anthropic.ClaudeCodeServer("Claude", { cwd: "/workspace/app" }),
);

Or on an AWS Lambda microVM

// src/Sandbox.microvm.ts
import * as Anthropic from "alchemy/Anthropic";
import * as AWS from "alchemy/AWS";
import { Sandbox } from "./Sandbox.ts";

export default AWS.Lambda.MicrovmSandbox(
  Sandbox,
  {
    main: import.meta.url,
    sizes: { small: "1 GB", large: "2 GB" }, // one microVM image per size
  },
  Anthropic.ClaudeCodeServer("Claude", { cwd: "/workspace/app" }),
);

AWS.Lambda.MicrovmSandbox(Sandbox, { main: import.meta.url, sizes: { small: "1 GB" } }, program);
// ✗ Property 'large' is missing in type '{ small: "1 GB" }'

Declare a gateway

// src/gateway.ts
import * as Anthropic from "alchemy/Anthropic";
import * as Egress from "alchemy/Egress";
import * as GitHub from "alchemy/GitHub";

export class WorkGateway extends Egress.Gateway<WorkGateway>()("WorkGateway", {
  model: Anthropic.Egress,
  repo: GitHub.Egress,
}) {}

Serve it

// src/gateway.worker.ts
import * as Anthropic from "alchemy/Anthropic";
import * as Cloudflare from "alchemy/Cloudflare";
import * as GitHub from "alchemy/GitHub";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import { WorkGateway } from "./gateway.ts";

export default class WorkGatewayWorker extends Cloudflare.Worker<WorkGatewayWorker>()(
  "WorkGateway",
  { main: import.meta.url },
  WorkGateway.serve(
    Effect.gen(function* () {
      return {
        model: yield* Anthropic.Egress({ apiKey: Config.Redacted("ANTHROPIC_API_KEY") }),
        repo: yield* GitHub.Egress({
          token: GitHub.ProfileToken,
          repositories: [
            {
              repository: "alchemy-run/alchemy",
              contents: "write",
              pullRequests: "write",
              issues: "write",
              push: { branches: ["agent/**"] },
            },
          ],
        }),
      };
    }),
  ),
) {}

Or serve it on AWS Lambda

// src/gateway.lambda.ts
import * as AWS from "alchemy/AWS";
import { WorkGateway } from "./gateway.ts";
import { implementation } from "./gateway.impl.ts";

// Sandbox traffic → the function URL; mint → lambda:InvokeFunction (IAM), never the URL
export default AWS.Lambda.Function(
  "WorkGateway",
  { main: import.meta.url, url: true },
  WorkGateway.serve(implementation),
);

Credentials per user

// src/gateway.user.ts
import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import * as GitHub from "alchemy/GitHub";
import { Tokens } from "./db.ts";
import { UserGateway } from "./gateway.ts";

export default class UserGatewayWorker extends Cloudflare.Worker<UserGatewayWorker>()(
  "UserGateway",
  { main: import.meta.url },
  UserGateway.serve(
    Effect.gen(function* () {
      const tokens = yield* Cloudflare.KV.ReadNamespace(Tokens);
      return {
        // `subject` comes from the signed grant; resolved per request, in the gateway
        repo: yield* GitHub.Egress({
          token: ({ subject }) => tokens.get(subject).pipe(Effect.map((token) => token!)),
        }),
      };
    }),
  ),
) {}

Grant egresses to a sandbox

// src/Agent.ts
import * as Cloudflare from "alchemy/Cloudflare";
import * as Effect from "effect/Effect";
import { UserGateway, WorkGateway } from "./gateway.ts";
import { Sandbox } from "./Sandbox.ts";

export class Agent extends Cloudflare.DurableObject<Agent>()(
  "Agent",
  Effect.gen(function* () {
    const sandbox = yield* Sandbox;
    const work = yield* WorkGateway;
    const user = yield* UserGateway;

    return Effect.gen(function* () {
      return {
        work: (issue: number, userId: string) =>
          sandbox.start({
            size: "large",
            egress: [
              work.model,
              work.repo.narrow({ repository: "alchemy-run/alchemy", issue }),
              user.repo.narrow({ repository: "sam/dotfiles", graphql: false }).for(userId),
            ],
            ttl: "5 minutes",
          }),
        modelOnly: () => sandbox.setEgress({ egress: [work.model] }), // applies to the running sandbox
        settle: () => sandbox.stop(),
      };
    });
  }),
) {}

work.stripe;
// ✗ Property 'stripe' does not exist on type 'WorkGateway'
work.repo.narrow({ repo: "alchemy-run/alchemy" });
// ✗ 'repo' does not exist in type 'GitHub.Scope'

Provide the hosts

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Cloudflare from "alchemy/Cloudflare";
import * as GitHub from "alchemy/GitHub";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import { UserGateway, WorkGateway } from "./src/gateway.ts";
import UserGatewayWorker from "./src/gateway.user.ts";
import WorkGatewayWorker from "./src/gateway.worker.ts";
import SandboxLive from "./src/Sandbox.cloudflare.ts"; // or ./src/Sandbox.microvm.ts
import Api from "./src/worker.ts";

export default Alchemy.Stack(
  "Agents",
  {
    providers: Layer.mergeAll(Cloudflare.providers(), GitHub.providers()),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const api = yield* Api;
    return { api: api.url.as<string>() };
  }).pipe(
    Effect.provide(
      Layer.mergeAll(
        SandboxLive,
        WorkGateway.host(WorkGatewayWorker),
        UserGateway.host(UserGatewayWorker),
      ),
    ),
  ),
);

Close the internet on a microVM

// with egress, start() defaults to enableInternet: false: the proxy refuses hosts without a route
yield* sandbox.start({ size: "large", egress: [work.repo.narrow({ repository, issue })] });

// a microVM can't firewall itself (no CAP_NET_ADMIN): a VPC egress connector closes tools that ignore HTTPS_PROXY
export default AWS.Lambda.MicrovmSandbox(
  Sandbox,
  {
    main: import.meta.url,
    sizes: { small: "2 GB", large: "8 GB" },
    networkConnector: AWS.Lambda.NetworkConnector("SandboxEgress", {
      subnetIds: [privateSubnetId],
      securityGroupIds: [gatewaysOnlySecurityGroupId],
    }),
  },
  program,
);

What the sandbox sees

$ echo $GH_TOKEN
alchemy-egress
$ git push origin HEAD:main
 ! [remote rejected] HEAD -> main (alchemy egress: push to refs/heads/main is not allowed)
$ gh api repos/alchemy-run/distilled   # not granted: goes out with no credential

How a request reaches the gateway

Cloudflare Container                      AWS microVM (and anything else)
  git push                                  git push
   └ interceptOutboundHttps                  └ proxy :3128 (HTTPS_PROXY, per-sandbox CA)
     → AlchemyEgress relay entrypoint          routes by host + path
       (routes in props; mints grants          grant pushed by the Durable Object,
        over the gateway's service binding)    renewed before it expires
     → gateway (service binding)              → gateway (HTTPS + grant)
                                   ▼
            gateway: verify grant → rules → credential → github.com

Harness: sessions that survive restarts

const harness = yield* Cloudflare.Containers.Harness(Sandbox, { workspace: "/workspace/app" });

const claude = yield* harness.start({ size: "large", egress: [work.model, work.repo] }); // restores snapshot or checkpoint
const session = yield* claude.start({ id: "issue-42" });
yield* session.prompt("Fix the flaky test");

harness.events("issue-42", { after: 0 }); // from the DO's SQLite, no container
yield* harness.stop(); // checkpoint, snapshot, stop

Harness servers

// the whole program
Anthropic.ClaudeCodeServer("Claude", { cwd: "/workspace/app" });
// or OpenAI.CodexServer, OpenCode.Server, AI.AcpServer({ command, args })

// next to your own routes
Effect.gen(function* () {
  const claude = yield* Anthropic.ClaudeCodeServer("Claude", { cwd: "/workspace/app" });
  return {
    fetch: Effect.gen(function* () {
      const request = yield* HttpServerRequest;
      if (request.url === "/health") return HttpServerResponse.text("ok");
      return yield* claude.fetch;
    }),
  };
});

Vendor providers

const project = yield* OpenAI.Project("agents", {});
const fleet = yield* OpenAI.ServiceAccount("fleet", { projectId: project.projectId });
const budget = yield* OpenRouter.ApiKey("agent-42", { limit: 20, limitReset: "monthly" });
const workspace = yield* Anthropic.Workspace("agents", {});
const ModelLive = Anthropic.LanguageModel({ model: "claude-opus-5-5" });

services/harness

cd services/harness
bun alchemy deploy   # one Durable Object per issue, terminal, machine stats, pause / resume / settle

Removed

- GitHub.MountRepository / Git.MountRepository / Cloudflare.Artifacts.MountRepository
- AI.LocalHarness, Cloudflare.ContainerHarness
- AI.SessionRpcs, AI.makeSessionHandlers, AI.serveHarnessHttp
- Cloudflare.Containers.Egress, GitHub.Egress(container, …), Anthropic.Egress(container, …)
- sandbox.addEgress / sandbox.removeEgress

Design: packages/alchemy/src/Egress/DESIGN.md. Bumps distilled to alchemy-run/distilled#754.

🤖 Generated with Claude Code

[alchemy-version-bot]

Install the packages built from this commit:

alchemy

pnpm install https://pkg.alchemy.run/alchemy/pr:2019:884c091

@alchemy.run (6)

pnpm install https://pkg.alchemy.run/@alchemy.run/better-auth/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@alchemy.run/cloudflare-runtime/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@alchemy.run/frontend-frameworks/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@alchemy.run/node-utils/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@alchemy.run/floci/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@alchemy.run/pkg/pr:2019:884c091

Transitive Dependencies (25)

pnpm install https://pkg.alchemy.run/@distilled.cloud/acme/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/acp/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/anthropic/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/aws/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/axiom/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/cloudflare/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/codex/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/core/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/doppler/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/fly-io/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/gcp/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/hetzner/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/iceberg/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/infisical/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/neon/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/openai/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/opencode/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/openrouter/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/planetscale/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/prisma/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/railway/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/stripe/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/turso/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/zerossl/pr:2019:884c091

pnpm install https://pkg.alchemy.run/@distilled.cloud/github/pr:2019:884c091

Published Oct 16, 2026, 3:11 AM UTC. Expires Oct 23, 2026, 3:11 AM UTC, extended while this pull request is open.