Transactional

Quickstart

Create your first sandbox — spin up an isolated environment, run commands, read and write files, and clean up.

Install the SDK

npm install @usetransactional/node

Create a Sandbox

import Transactional from '@usetransactional/node';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
const sandbox = await tx.sandboxes.create({
  runtime: 'python-3.12',
  timeout: 300, // auto-destroy after 5 minutes
});
 
console.log('Sandbox ID:', sandbox.id);
console.log('Status:', sandbox.status); // 'running'

Run a Command

Execute any shell command inside the sandbox:

const result = await tx.sandboxes.run(sandbox.id, {
  command: 'python3',
  args: ['-c', 'print("Hello from the sandbox!")'],
});
 
console.log(result.stdout); // "Hello from the sandbox!"
console.log(result.exitCode); // 0

Install Packages

Sandboxes have full package managers available:

await tx.sandboxes.run(sandbox.id, {
  command: 'pip',
  args: ['install', 'pandas', 'numpy'],
});
 
const analysis = await tx.sandboxes.run(sandbox.id, {
  command: 'python3',
  args: ['-c', `
import pandas as pd
import numpy as np
 
data = pd.DataFrame({
    'product': ['Widget A', 'Widget B', 'Widget C'],
    'revenue': [1200, 3400, 890]
})
 
print(f"Total revenue: ${data['revenue'].sum()}")
print(f"Average: ${data['revenue'].mean():.2f}")
  `],
});
 
console.log(analysis.stdout);

Write Files

Write files to the sandbox filesystem:

await tx.sandboxes.writeFile(sandbox.id, {
  path: '/home/user/data.json',
  content: JSON.stringify({
    users: [
      { name: 'Alice', score: 95 },
      { name: 'Bob', score: 87 },
    ],
  }),
});

Read Files

Read files back from the sandbox:

const file = await tx.sandboxes.readFile(sandbox.id, {
  path: '/home/user/data.json',
});
 
console.log('File contents:', file.content);

List Files

List directory contents:

const listing = await tx.sandboxes.run(sandbox.id, {
  command: 'ls',
  args: ['-la', '/home/user/'],
});
 
console.log(listing.stdout);

Destroy the Sandbox

Clean up when you are done:

await tx.sandboxes.destroy(sandbox.id);
console.log('Sandbox destroyed');

Sandboxes are also automatically destroyed when their timeout expires.

Error Handling

Handle sandbox errors gracefully:

try {
  const result = await tx.sandboxes.run(sandbox.id, {
    command: 'python3',
    args: ['-c', 'raise ValueError("Something went wrong")'],
  });
 
  if (result.exitCode !== 0) {
    console.error('Script failed:', result.stderr);
  }
} catch (error) {
  console.error('Sandbox error:', error.message);
} finally {
  await tx.sandboxes.destroy(sandbox.id);
}

Next Steps