JavaScript/TypeScript SDK

import { ConnectionConfig, Sandbox, SandboxException } from "@alibaba-group/opensandbox";

const config = new ConnectionConfig({
  domain: "api.opensandbox.io",
  apiKey: "your-api-key",
  // protocol: "https",
  // requestTimeoutSeconds: 60,
});

try {
  const sandbox = await Sandbox.create({
    connectionConfig: config,
    image: "ubuntu",
    timeoutSeconds: 10 * 60,
  });

  const execution = await sandbox.commands.run("echo 'Hello Sandbox!'");
  console.log(execution.logs.stdout[0]?.text);

  // Optional but recommended: terminate the remote instance when you are done.
  await sandbox.kill();
  await sandbox.close();
} catch (err) {
  if (err instanceof SandboxException) {
    console.error(
      `Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`,
    );
  } else {
    console.error(err);
  }
}

const info = await sandbox.getInfo();
console.log("State:", info.status.state);
console.log("Created:", info.createdAt);
console.log("Expires:", info.expiresAt);

await sandbox.pause();

// Resume returns a fresh, connected Sandbox instance.
const resumed = await sandbox.resume();

// Renew: expiresAt = now + timeoutSeconds
await resumed.renew(30 * 60);

const sandbox = await Sandbox.create({
  connectionConfig: config,
  image: "nginx:latest",
  healthCheck: async (sbx) => {
    // Example: consider the sandbox healthy when port 80 endpoint becomes available
    const ep = await sbx.getEndpoint(80);
    return !!ep.endpoint;
  },
});

import type { ExecutionHandlers } from "@alibaba-group/opensandbox";

const handlers: ExecutionHandlers = {
  onStdout: (m) => console.log("STDOUT:", m.text),
  onStderr: (m) => console.error("STDERR:", m.text),
  onExecutionComplete: (c) =>
    console.log("Finished in", c.executionTimeMs, "ms"),
};

await sandbox.commands.run(
  'for i in 1 2 3; do echo "Count $i"; sleep 0.2; done',
  undefined,
  handlers,
);

await sandbox.files.createDirectories([{ path: "/tmp/demo", mode: 755 }]);

await sandbox.files.writeFiles([
  { path: "/tmp/demo/hello.txt", data: "Hello World", mode: 644 },
]);

const content = await sandbox.files.readFile("/tmp/demo/hello.txt");
console.log("Content:", content);

const files = await sandbox.files.search({
  path: "/tmp/demo",
  pattern: "*.txt",
});
console.log(files.map((f) => f.path));

await sandbox.files.deleteDirectories(["/tmp/demo"]);

const { endpoint } = await sandbox.getEndpoint(44772);
const url = await sandbox.getEndpointUrl(44772);

import { SandboxManager } from "@alibaba-group/opensandbox";

const manager = SandboxManager.create({ connectionConfig: config });
const list = await manager.listSandboxInfos({
  states: ["Running"],
  pageSize: 10,
});
console.log(list.items.map((s) => s.id));
await manager.close();

const sandbox = await Sandbox.create({
  connectionConfig: config,
  image: "python:3.11",
  networkPolicy: {
    defaultAction: "deny",
    egress: [{ action: "allow", target: "pypi.org" }],
  },
});

const sandbox = await Sandbox.create({ ... });
// ... use sandbox ...
await sandbox.close();

await sandbox.files.writeFiles([
  {
    path: "/app/script.js",
    data: `
console.log('Node version:', process.version);
console.log('Hello from OpenSandbox!');
    `,
    mode: 755,
  },
]);

const execution = await sandbox.commands.run("node /app/script.js");
execution.logs.stdout.forEach((line) => console.log(line.text));

const sandbox = await Sandbox.create({
  connectionConfig: config,
  image: "node:20",
  networkPolicy: {
    defaultAction: "deny",
    egress: [
      { action: "allow", target: "npmjs.org" },
      { action: "allow", target: "registry.npmjs.org" },
    ],
  },
});

// Start a web server in the sandbox
await sandbox.commands.run(
  "node -e 'require(\"http\").createServer((req,res)=>res.end(\"Hello\")).listen(8000)'",
  { background: true },
);

// Get the external URL
const url = await sandbox.getEndpointUrl(8000);
console.log(`Access your server at: ${url}`);

import { SandboxException } from "@alibaba-group/opensandbox";

try {
  const sandbox = await Sandbox.create({
    connectionConfig: config,
    image: "ubuntu",
  });
  const execution = await sandbox.commands.run("ls -la");
} catch (err) {
  if (err instanceof SandboxException) {
    console.error(`Error [${err.error.code}]: ${err.error.message}`);
  } else {
    throw err;
  }
}

import type {
  Sandbox,
  SandboxInfo,
  Execution,
  ExecutionHandlers,
  WriteEntry,
  SearchEntry,
  NetworkPolicy,
} from "@alibaba-group/opensandbox";