Skip to main content

Documentation Index

Fetch the complete documentation index at: https://code.storage/docs/llms.txt

Use this file to discover all available pages before exploring further.

Sandbox environments let you run code in isolated, ephemeral containers. Using Git as your source of truth—rather than provider-specific storage like volumes—gives you version history, branching, and portability across any sandbox provider. Code Storage integrates with popular sandbox providers through authenticated Git URLs—generate a URL with the SDK, then clone inside your sandbox.
Note: For fastest cloning in ephemeral environments, consider using a shallow single-branch clone – this skips commit history and other branches—ideal for sandboxes where you only need the latest code: 
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 pushing changes)
const writeUrl = await repo.getRemoteURL({
  permissions: ['git:read', 'git:write'],
  ttl: 3600,
});
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();
}

​
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();
}

​
Daytona

Daytona provides secure sandboxes for AI agents. Clone repositories using Daytona’s built-in Git API, 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 using 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');

  // Make changes and commit using Git API
  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();
}

​
Ephemeral branches for isolation

Use ephemeral branches to isolate sandbox work from your main codebase. Changes stay in the ephemeral namespace until you promote them. 
const repo = await store.findOne({ id: 'my-project' });

// Get URL for ephemeral namespace
const ephemeralUrl = await repo.getEphemeralRemoteURL({
  permissions: ['git:read', 'git:write'],
  ttl: 3600,
});

// In your sandbox:
// git clone --depth 1 --single-branch <ephemeralUrl> repo
// git checkout -b sandbox/experiment-123
// ... make changes ...
// git push -u origin sandbox/experiment-123

// When ready, promote the ephemeral branch
await repo.promoteEphemeralBranch({
  baseBranch: 'sandbox/experiment-123',
  targetBranch: 'feature/new-capability',
});

​
Provider resilience

Many teams run multiple sandbox providers for maximum resilience. With Git as your source of truth, you can failover between providers without losing work—if one has an outage or capacity issues, spin up a sandbox elsewhere and 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();
  }
}
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.
  • Ephemeral branches: Isolate experimental or untrusted code in the ephemeral namespace.
  • Audit commits: When sandboxes push code, review changes before merging to protected branches.