Connect a Sandbox

Sandbox environments let you run code in isolated, temporary containers. Use Git as your source of truth instead of provider-specific storage, such as volumes. Git gives you version history, branches, and portability across sandbox providers. Generate an authenticated Git URL with the Code Storage SDK. Use the URL to clone the repository in your sandbox. Use this guide to connect a sandbox provider. To isolate agent writes and keep durable state, see Store Session State.

Note: Use a shallow, single-branch clone to reduce the clone time. This clone omits the commit history and other branches:

git clone --depth 1 --single-branch <url> repo

Quick start

Generate an authenticated Git URL and use it inside any sandbox:

import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY,
});

const repo = await store.findOne({ id: 'my-project' });

// Read-only access
const readUrl = await repo.getRemoteURL({
  permissions: ['git:read'],
  ttl: 3600,
});

// Read-write access (for pushes)
const writeUrl = await repo.getRemoteURL({
  permissions: ['git:read', 'git:write'],
  ttl: 3600,
});

import os
from pierre_storage import GitStorage

storage = GitStorage({
    "name": "your-org",
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

repo = await storage.find_one(id="my-project")

# Read-only access
read_url = await repo.get_remote_url(
    permissions=["git:read"],
    ttl=3600,
)

# Read-write access (for pushes)
write_url = await repo.get_remote_url(
    permissions=["git:read", "git:write"],
    ttl=3600,
)

ctx := context.Background()

// Find the repository
repo, err := client.FindOne(ctx, storage.FindOneOptions{ID: "my-project"})

// Read-only access
readURL, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead},
	TTL:         time.Hour,
})

// Read-write access (for pushes)
writeURL, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
	TTL:         time.Hour,
})

Confine a sandbox to one session branch

Give the agent two short-lived URLs. Use a read-only normal URL for fetches. Use an ephemeral URL for pushes. Use refPolicies to confine it to one branch.

const readUrl = await repo.getRemoteURL({
  permissions: ['git:read'],
  ttl: 3600,
});

const sessionRef = `refs/namespaces/ephemeral/refs/heads/${sessionBranch}`;
const writeUrl = await repo.getEphemeralRemoteURL({
  permissions: ['git:read', 'git:write'],
  refPolicies: [
    { ops: ['no-force-push'], pattern: sessionRef },
    { ops: ['no-push'], pattern: '*' },
  ],
  ttl: 3600,
});

read_url = await repo.get_remote_url(
    permissions=["git:read"],
    ttl=3600,
)

session_ref = f"refs/namespaces/ephemeral/refs/heads/{session_branch}"
write_url = await repo.get_ephemeral_remote_url(
    permissions=["git:read", "git:write"],
    ref_policies=[
        {"ops": ["no-force-push"], "pattern": session_ref},
        {"ops": ["no-push"], "pattern": "*"},
    ],
    ttl=3600,
)

readURL, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead},
	TTL:         time.Hour,
})

sessionRef := fmt.Sprintf("refs/namespaces/ephemeral/refs/heads/%s", sessionBranch)
writeURL, err := repo.EphemeralRemoteURL(ctx, storage.RemoteURLOptions{
	Permissions: []storage.Permission{
		storage.PermissionGitRead,
		storage.PermissionGitWrite,
	},
	RefPolicies: storage.RefPolicyList{
		{Ops: storage.Ops{storage.OpNoForcePush}, Pattern: sessionRef},
		{Ops: storage.Ops{storage.OpNoPush}, Pattern: "*"},
	},
	TTL: time.Hour,
})

Set the normal URL as the fetch URL and the ephemeral URL as the push URL before the agent starts. Pass the base commit SHA as BASE_SHA. Pass sessionBranch as SESSION_BRANCH.

git clone --depth 1 --single-branch --no-checkout "$READ_URL" work
cd work
git fetch origin "$BASE_SHA"
git remote set-url --push origin "$WRITE_URL"
git switch -c "$SESSION_BRANCH" "$BASE_SHA"

# The agent changes files and creates commits.
git push origin "$SESSION_BRANCH"

The sandbox keeps one origin with separate URLs for fetches and pushes. A stray git push origin main goes to the ephemeral namespace. The sandbox has no credential that can write to a normal branch. The policy permits fast-forward pushes to this session branch only. It rejects all other pushes. See Store Session State for the branch layout, and Ref Policies for the refPolicies rules. Modal provides serverless cloud functions with persistent volumes. Clone repositories into volumes, run code, and push changes back.

import { ModalClient } from 'modal';
import { GitStorage } from '@pierre/storage';

const modal = new ModalClient();
const store = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY,
});

async function runInModalSandbox(repoId: string) {
  const repo = await store.findOne({ id: repoId });
  const url = await repo.getRemoteURL({
    permissions: ['git:read', 'git:write'],
    ttl: 3600,
  });

  // Create a Modal sandbox
  const app = await modal.apps.fromName('code-runner', { createIfMissing: true });
  const image = modal.images.fromRegistry('python:3.12-slim');
  const sb = await modal.sandboxes.create(app, image);

  // Shallow clone for speed
  await sb.exec(['git', 'clone', '--depth', '1', '--single-branch', url, '/code/repo']);
  await sb.exec(['git', 'config', '--global', 'user.email', 'agent@example.com']);
  await sb.exec(['git', 'config', '--global', 'user.name', 'AI Agent']);

  // Run tests or make changes
  const result = await sb.exec(['pytest', '/code/repo/tests']);
  console.log(await result.stdout.readText());

  // Commit and push changes
  await sb.exec(['git', '-C', '/code/repo', 'add', '.']);
  await sb.exec(['git', '-C', '/code/repo', 'commit', '-m', 'Update from sandbox']);
  await sb.exec(['git', '-C', '/code/repo', 'push']);

  await sb.terminate();
}

import modal
import subprocess
import os
from pierre_storage import GitStorage

app = modal.App("code-runner")
vol = modal.Volume.from_name("code-cache", create_if_missing=True)

storage = GitStorage({
    "name": "your-org",
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

@app.function(volumes={"/code": vol})
async def run_in_sandbox(repo_id: str):
    repo = await storage.find_one(id=repo_id)
    url = await repo.get_remote_url(
        permissions=["git:read", "git:write"],
        ttl=3600,
    )

    # Shallow clone for speed
    subprocess.run(
        ["git", "clone", "--depth", "1", "--single-branch", url, "/code/repo"],
        check=True,
    )
    subprocess.run(
        ["git", "config", "--global", "user.email", "agent@example.com"],
        check=True,
    )
    subprocess.run(
        ["git", "config", "--global", "user.name", "AI Agent"],
        check=True,
    )

    # Run tests or make changes
    subprocess.run(["pytest", "/code/repo/tests"], check=True)

    # Commit and push changes
    subprocess.run(["git", "-C", "/code/repo", "add", "."], check=True)
    subprocess.run(
        ["git", "-C", "/code/repo", "commit", "-m", "Update from sandbox"],
        check=True,
    )
    subprocess.run(["git", "-C", "/code/repo", "push"], check=True)

    vol.commit()

// Generate a Git URL, then use your sandbox provider's API or shell to clone and run commands
repo, err := client.FindOne(context.Background(), storage.FindOneOptions{ID: "my-project"})

// Read-write access (for pushes)
url, err := repo.RemoteURL(context.Background(), storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
	TTL:         time.Hour,
})

// Example shell commands inside a sandbox:
// exec.Command("git", "clone", "--depth", "1", "--single-branch", url, "/code/repo").Run()
// exec.Command("git", "-C", "/code/repo", "push").Run()

E2B

E2B provides cloud sandboxes for AI agents. Clone repositories, execute code, and push results back to Code Storage.

import { Sandbox } from 'e2b';
import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY,
});

async function runAgentTask(repoId: string) {
  const repo = await store.findOne({ id: repoId });
  const url = await repo.getRemoteURL({
    permissions: ['git:read', 'git:write'],
    ttl: 3600,
  });

  const sandbox = await Sandbox.create();

  // Shallow clone for speed
  await sandbox.commands.exec(`git clone --depth 1 --single-branch ${url} /home/user/repo`);
  await sandbox.commands.exec('git config --global user.email "agent@example.com"');
  await sandbox.commands.exec('git config --global user.name "AI Agent"');

  // Run commands and make changes
  await sandbox.commands.exec('cd /home/user/repo && npm install');
  await sandbox.commands.exec('cd /home/user/repo && npm test');

  // Agent generates new code...
  await sandbox.commands.exec('echo "// Generated by AI" >> /home/user/repo/src/index.ts');

  // Commit and push
  await sandbox.commands.exec('cd /home/user/repo && git add .');
  await sandbox.commands.exec('cd /home/user/repo && git commit -m "Agent changes"');
  await sandbox.commands.exec('cd /home/user/repo && git push');

  await sandbox.kill();
}

import os
from e2b import Sandbox
from pierre_storage import GitStorage

storage = GitStorage({
    "name": "your-org",
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

async def run_agent_task(repo_id: str):
    repo = await storage.find_one(id=repo_id)
    url = await repo.get_remote_url(
        permissions=["git:read", "git:write"],
        ttl=3600,
    )

    sandbox = Sandbox()

    # Shallow clone for speed
    sandbox.commands.run(f"git clone --depth 1 --single-branch {url} /home/user/repo")
    sandbox.commands.run('git config --global user.email "agent@example.com"')
    sandbox.commands.run('git config --global user.name "AI Agent"')

    # Run commands and make changes
    sandbox.commands.run("cd /home/user/repo && pip install -r requirements.txt")
    sandbox.commands.run("cd /home/user/repo && pytest")

    # Agent generates new code...
    sandbox.commands.run('echo "# Generated by AI" >> /home/user/repo/main.py')

    # Commit and push
    sandbox.commands.run("cd /home/user/repo && git add .")
    sandbox.commands.run('cd /home/user/repo && git commit -m "Agent changes"')
    sandbox.commands.run("cd /home/user/repo && git push")

    sandbox.kill()

// Find the repository
repo, err := client.FindOne(context.Background(), storage.FindOneOptions{ID: "my-project"})

// Generate a Git URL with read-write access
url, err := repo.RemoteURL(context.Background(), storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
	TTL:         time.Hour,
})

// In your sandbox shell:
// git clone --depth 1 --single-branch <url> /home/user/repo
// git -C /home/user/repo push

Daytona

Daytona provides secure sandboxes for AI agents. Use Daytona’s built-in Git API to clone repositories. Run commands and push changes back.

import { Daytona } from '@daytonaio/sdk';
import { GitStorage } from '@pierre/storage';

const store = new GitStorage({
  name: 'your-org',
  key: process.env.PIERRE_PRIVATE_KEY,
});

const daytona = new Daytona();

async function runInDaytona(repoId: string) {
  const repo = await store.findOne({ id: repoId });
  const url = await repo.getRemoteURL({
    permissions: ['git:read', 'git:write'],
    ttl: 3600,
  });

  // Create sandbox
  const sandbox = await daytona.create();

  // Clone with Daytona's Git API
  await sandbox.git.clone(url, '/home/daytona/repo');

  // Run commands
  await sandbox.process.executeCommand('npm install', '/home/daytona/repo');
  await sandbox.process.executeCommand('npm test', '/home/daytona/repo');

  // Use the Git API to change and commit files
  await sandbox.git.add('/home/daytona/repo', ['.']);
  await sandbox.git.commit(
    '/home/daytona/repo',
    'Update from sandbox',
    'AI Agent',
    'agent@example.com',
  );
  await sandbox.git.push('/home/daytona/repo');

  await sandbox.delete();
}

import os
from daytona_sdk import Daytona
from pierre_storage import GitStorage

storage = GitStorage({
    "name": "your-org",
    "key": os.environ["PIERRE_PRIVATE_KEY"],
})

daytona = Daytona()

async def run_in_daytona(repo_id: str):
    repo = await storage.find_one(id=repo_id)
    url = await repo.get_remote_url(
        permissions=["git:read", "git:write"],
        ttl=3600,
    )

    # Create sandbox
    sandbox = daytona.create()

    # Clone with Daytona's Git API
    sandbox.git.clone(url, "/home/daytona/repo")

    # Run commands
    sandbox.process.exec("pip install -r requirements.txt", cwd="/home/daytona/repo")
    sandbox.process.exec("pytest", cwd="/home/daytona/repo")

    # Use the Git API to change and commit files
    sandbox.git.add("/home/daytona/repo", ["."])
    sandbox.git.commit("/home/daytona/repo", "Update from sandbox", "AI Agent", "agent@example.com")
    sandbox.git.push("/home/daytona/repo")

    sandbox.delete()

// Find the repository
repo, err := client.FindOne(context.Background(), storage.FindOneOptions{ID: "my-project"})

// Generate a Git URL with read-write access
url, err := repo.RemoteURL(context.Background(), storage.RemoteURLOptions{
	Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
	TTL:         time.Hour,
})

// Use the Daytona Go SDK if available, or run git commands in the sandbox shell.

Provider resilience

Many teams use multiple sandbox providers to improve resilience. Git keeps your code portable across providers. If one provider has an outage or no capacity, start a sandbox elsewhere. Then clone the same repository:

async function runWithFallback(repoId: string, task: () => Promise<void>) {
  const repo = await store.findOne({ id: repoId });
  const url = await repo.getRemoteURL({
    permissions: ['git:read', 'git:write'],
    ttl: 3600,
  });

  try {
    // Try primary provider
    const e2b = await E2BSandbox.create();
    await e2b.commands.exec(`git clone --depth 1 --single-branch ${url} /repo`);
    await task();
  } catch (err) {
    // Fallback to secondary provider
    const daytona = new Daytona();
    const sandbox = await daytona.create();
    await sandbox.git.clone(url, '/repo');
    await task();
  }
}

async def run_with_fallback(repo_id: str, task):
    repo = await storage.find_one(id=repo_id)
    url = await repo.get_remote_url(
        permissions=["git:read", "git:write"],
        ttl=3600,
    )

    try:
        # Try primary provider
        e2b = Sandbox()
        e2b.commands.run(f"git clone --depth 1 --single-branch {url} /repo")
        await task()
    except Exception:
        # Fallback to secondary provider
        daytona = Daytona()
        sandbox = daytona.create()
        sandbox.git.clone(url, "/repo")
        await task()

func runWithFallback(ctx context.Context, repoID string, task func() error) error {
	repo, err := client.FindOne(ctx, storage.FindOneOptions{ID: repoID})
	if err != nil {
		return err
	}
	url, err := repo.RemoteURL(ctx, storage.RemoteURLOptions{
		Permissions: []storage.Permission{storage.PermissionGitRead, storage.PermissionGitWrite},
		TTL:         time.Hour,
	})
	if err != nil {
		return err
	}

	// Try primary provider...
	if err := task(); err != nil {
		// Use the same URL for the secondary provider.
		return task()
	}
	return nil
}

Your code stays safe in Code Storage regardless of which sandbox runs it.

Security considerations

Short TTLs: Use the shortest TTL practical for your use case. Sandbox sessions are typically short-lived.
Minimal permissions: Grant git:read only unless the sandbox needs to push changes.
Agent state: Store experimental or untrusted work on ephemeral branches. See Store Session State.
Audit commits: Review sandbox changes before you merge them into protected branches.

Getting Started

Features

Workflows

Reference

Quick start

Confine a sandbox to one session branch

E2B

Daytona

Provider resilience

Security considerations

​Quick start

​Confine a sandbox to one session branch

​Modal

​E2B

​Daytona

​Provider resilience

​Security considerations

Quick start

Confine a sandbox to one session branch

Modal

E2B

Daytona

Provider resilience

Security considerations