Connect to Workers bindings

Last updated Sep 30, 2026 Note

This page documents Sandbox SDK 0.x for existing applications. For new applications, refer to Sandboxes. To move an existing application to @cloudflare/sandbox 1.0, refer to Migrate from Sandbox SDK 0.x.

Sandboxes can access Workers bindings — KV, R2, D1, Durable Objects, and others — through outbound handlers. An outbound handler intercepts HTTP requests from the sandbox and runs inside the Workers runtime, where all of your configured bindings are available.

The sandbox makes a plain HTTP request to a virtual hostname (for example, http://my.kv/some-key), and the outbound handler resolves it using the bound resource. No SDK or client library is required inside the sandbox.

Use bindings in outbound handlers

Define an outboundByHost handler for each virtual hostname. The env argument gives you access to every binding declared in your Wrangler configuration.

export class MySandbox extends Sandbox {}

MySandbox.outboundByHost = {
    "my.kv": async (request, env, ctx) => {
        const url = new URL(request.url);
        const key = url.pathname.slice(1);
        const value = await env.KV.get(key);
        return new Response(value ?? "", { status: value ? 200 : 404 });
    },
    "my.r2": async (request, env, ctx) => {
        const url = new URL(request.url);
        // Scope access to this sandbox's ID
        const path = `${ctx.containerId}${url.pathname}`;
        const object = await env.R2.get(path);
        return new Response(object?.body ?? null, { status: object ? 200 : 404 });
    },
};

export class MySandbox extends Sandbox {}

MySandbox.outboundByHost = {
    "my.kv": async (request: Request, env: Env, ctx: OutboundHandlerContext) => {
        const url = new URL(request.url);
        const key = url.pathname.slice(1);
        const value = await env.KV.get(key);
        return new Response(value ?? "", { status: value ? 200 : 404 });
    },
    "my.r2": async (request: Request, env: Env, ctx: OutboundHandlerContext) => {
        const url = new URL(request.url);
        // Scope access to this sandbox's ID
        const path = `${ctx.containerId}${url.pathname}`;
        const object = await env.R2.get(path);
        return new Response(object?.body ?? null, { status: object ? 200 : 404 });
    },
};

The sandbox calls http://my.kv/some-key and the handler resolves it using the KV binding. A call to http://my.r2/file.png reads from R2, scoped to the current sandbox instance.

Note

You can use ctx.containerId to apply different rules per sandbox instance — for example, to look up per-instance configuration from KV.

Access Durable Object state

The ctx argument exposes containerId, which lets you interact with the sandbox's own Durable Object from an outbound handler.

export class MySandbox extends Sandbox {}

MySandbox.outboundByHost = {
    "get-state.do": async (request, env, ctx) => {
        const id = env.MY_SANDBOX.idFromString(ctx.containerId);
        const stub = env.MY_SANDBOX.get(id);
        // Assumes getStateForKey is defined on your DO
        return stub.getStateForKey(request.body);
    },
};

export class MySandbox extends Sandbox {}

MySandbox.outboundByHost = {
    "get-state.do": async (
        request: Request,
        env: Env,
        ctx: { containerId: string },
    ) => {
        const id = env.MY_SANDBOX.idFromString(ctx.containerId);
        const stub = env.MY_SANDBOX.get(id);
        // Assumes getStateForKey is defined on your DO
        return stub.getStateForKey(request.body);
    },
};

Was this helpful?

YesNo

On this page

Connect to Workers bindings - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/sdk/guides/workers-connections/#page","headline":"Connect to Workers bindings","description":"Access KV, R2, Durable Objects, and other bindings from a Sandbox SDK 0.x sandbox.","url":"https://developers.cloudflare.com/sandbox/sdk/guides/workers-connections/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/sdk/guides/workers-connections/og.png?v=25b9d14a733d1d23","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Move a Sandbox SDK 0.x application to a Durable Object class that you write, which starts its own container, and find the page for each 0.x feature that you use. title: Migrate from Sandbox SDK 0.x image: https://developers.cloudflare.com/sandbox/sdk/migrate/og.png?v=aa4f59a0942cdaab

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.