Sandbox SDK + Artifacts

Last updated Sep 29, 2026 This example uses the git-repo-per-sandbox Sandbox SDK template and highlights the Artifacts-specific pieces.

Start from the template with create cloudflare, as shown in Create your project. Then adapt the Artifacts flow with the snippets in steps 1 to 3.

  • Creates or reuses a sandbox by ID.
  • Creates or reuses an Artifacts repo with the same ID.
  • Passes an authenticated Git remote into the sandbox as ARTIFACTS_GIT_REMOTE.

Create your project

npmyarnpnpm

npm create cloudflare@latest -- repo-per-sandbox --template=cloudflare/sandbox-sdk/examples/git-repo-per-sandbox#v0

yarn create cloudflare repo-per-sandbox --template=cloudflare/sandbox-sdk/examples/git-repo-per-sandbox#v0

pnpm create cloudflare@latest repo-per-sandbox --template=cloudflare/sandbox-sdk/examples/git-repo-per-sandbox#v0

cd repo-per-sandbox

1. Create or reuse the repo

The template keeps one Artifacts repo per sandbox ID. Use your own source of truth to decide whether this request should create a new repo or load an existing one.

src/index.jsjs

let defaultBranch;
let remote;
let token;
const sandboxWasJustCreated = true; // for example, set this when you create a new sandbox record

if (sandboxWasJustCreated) {
    const created = await env.ARTIFACTS.create(sandboxId);

    defaultBranch = created.defaultBranch;
    remote = created.remote;
    token = created.token;
} else {
    const repo = await env.ARTIFACTS.get(sandboxId);

    defaultBranch = repo.defaultBranch;
    remote = repo.remote;
    token = (await repo.createToken("write", 3600)).plaintext;
}

src/index.tsts

let defaultBranch: string;
let remote: string;
let token: string;
const sandboxWasJustCreated = true; // for example, set this when you create a new sandbox record

if (sandboxWasJustCreated) {
    const created = await env.ARTIFACTS.create(sandboxId);

    defaultBranch = created.defaultBranch;
    remote = created.remote;
    token = created.token;
} else {
    const repo = await env.ARTIFACTS.get(sandboxId);

    defaultBranch = repo.defaultBranch;
    remote = repo.remote;
    token = (await repo.createToken("write", 3600)).plaintext;
}

The template already knows the repo name, so start with direct lookup instead of scanning list() pages. Avoid broad catch blocks here. They can hide missing-repo, auth, and validation failures behind the same retry message.

If your flow can race with repo creation, handle that retry at the application level after you inspect the thrown error.

2. Create or reuse the sandbox

Use the same ID for the sandbox:

src/index.jsjs

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, sandboxId);

src/index.tsts

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, sandboxId);

3. Pass the repo into the sandbox

Convert the write token into an authenticated Git remote, then store it as an environment variable inside the sandbox.

Use a short-lived token and pass it into the sandbox only after the sandbox session is authorized to push changes.

src/index.jsjs

function toAuthenticatedRemote(remote, token) {
    const tokenSecret = token.split("?expires=")[0];
    return `https://x:${tokenSecret}@${remote.slice("https://".length)}`;
}

await sandbox.setEnvVars({
    ARTIFACTS_GIT_REMOTE: toAuthenticatedRemote(remote, token),
});

src/index.tsts

function toAuthenticatedRemote(remote: string, token: string) {
    const tokenSecret = token.split("?expires=")[0];
    return `https://x:${tokenSecret}@${remote.slice("https://".length)}`;
}

await sandbox.setEnvVars({
    ARTIFACTS_GIT_REMOTE: toAuthenticatedRemote(remote, token),
});

Code running inside the sandbox can then use ARTIFACTS_GIT_REMOTE with git clone, git fetch, git pull, or git push.

Was this helpful?

YesNo

On this page

Sandbox SDK + Artifacts - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/artifacts/examples/sandbox-sdk-artifacts/#page","headline":"Sandbox SDK + Artifacts","description":"Connect a sandbox to an Artifacts repo.","url":"https://developers.cloudflare.com/artifacts/examples/sandbox-sdk-artifacts/","inLanguage":"en","image":"https://developers.cloudflare.com/artifacts/examples/sandbox-sdk-artifacts/og.png?v=85fb0fd15abeaf49","dateModified":"2026-09-29","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: Review recent changes to Artifacts. title: Changelog image: https://developers.cloudflare.com/artifacts/platform/changelog/og.png?v=e190861fe23451a0

Skip to content

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