@agent-sandbox/cli 0.1.1

package/README.md

@@ -0,0 +1,89 @@
+# @agent-sandbox/cli
+
+Command-line interface for Agent Sandbox.
+
+## Install
+
+```bash
+npm install -g @agent-sandbox/cli
+```
+
+Install the agent skill:
+
+```bash
+npx skills add https://github.com/usamaasfar/agent-sandbox/tree/main/skills/agent-sandbox-cli
+```
+
+## Requirements
+
+- Docker running locally
+
+## Quick Start
+
+```bash
+agent-sandbox create
+agent-sandbox write <sandboxId> "printf 'hello\n' > /proc/1/fd/1"
+agent-sandbox read <sandboxId>
+agent-sandbox delete <sandboxId>
+```
+
+## Command Reference
+
+### `create`
+
+```bash
+agent-sandbox create [--name <name>] [--image <image>]
+```
+
+Prints the `sandboxId`.
+
+### `delete`
+
+```bash
+agent-sandbox delete <sandboxId>
+```
+
+### `list`
+
+```bash
+agent-sandbox list
+```
+
+Prints a JSON array of managed sandboxes.
+
+### `read`
+
+```bash
+agent-sandbox read <sandboxId> [--tail <n>]
+```
+
+Returns container logs. `--tail` limits to the last N lines.
+
+### `write`
+
+```bash
+agent-sandbox write <sandboxId> <input> [--detach]
+```
+
+Runs the command and returns its output and exit code. Use `--detach` to fire-and-forget
+(returns immediately with no output, useful for starting background processes).
+
+### `upload`
+
+```bash
+agent-sandbox upload <sandboxId> <localPath> <remotePath>
+```
+
+Both paths must be absolute.
+
+### `download`
+
+```bash
+agent-sandbox download <sandboxId> <remotePath> <localPath>
+```
+
+`remotePath` may be a file or directory. Both paths must be absolute.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,718 @@
+#!/usr/bin/env bun
+// @bun
+
+// ../../packages/core/src/errors.ts
+class SandboxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxError";
+  }
+}
+
+class ContainerNotFoundError extends SandboxError {
+  constructor(sandboxId) {
+    super(`Container not found: ${sandboxId}`);
+    this.name = "ContainerNotFoundError";
+  }
+}
+
+class DockerError extends SandboxError {
+  status;
+  constructor(status, message) {
+    super(`Docker API error ${status}: ${message}`);
+    this.name = "DockerError";
+    this.status = status;
+  }
+}
+
+class ExecError extends SandboxError {
+  constructor(message) {
+    super(`Exec failed: ${message}`);
+    this.name = "ExecError";
+  }
+}
+// ../../packages/core/src/docker/client.ts
+var DOCKER_HOST = "http://localhost";
+var CLIENT_API_VERSION = "1.53";
+var DOCKER_SOCKET_PATH = "/var/run/docker.sock";
+var cachedApiVersion = null;
+var resolvingApiVersion = null;
+function isRawBody(body) {
+  return typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || body instanceof FormData || body instanceof URLSearchParams || body instanceof ReadableStream || ArrayBuffer.isView(body);
+}
+function parseApiVersion(version) {
+  const match = version.match(/^(\d+)\.(\d+)$/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+function selectApiVersion(serverVersion) {
+  const client = parseApiVersion(CLIENT_API_VERSION);
+  const server = parseApiVersion(serverVersion);
+  if (!client || !server) {
+    return CLIENT_API_VERSION;
+  }
+  if (server[0] < client[0]) {
+    return serverVersion;
+  }
+  if (server[0] > client[0]) {
+    return CLIENT_API_VERSION;
+  }
+  return server[1] < client[1] ? serverVersion : CLIENT_API_VERSION;
+}
+function buildUrl(path, query, apiVersion = CLIENT_API_VERSION) {
+  const url = new URL(`${DOCKER_HOST}/v${apiVersion}${path}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+async function dockerFetch(input, init) {
+  return fetch(input, {
+    ...init,
+    unix: DOCKER_SOCKET_PATH
+  });
+}
+async function readDockerErrorMessage(response) {
+  let text = "";
+  try {
+    text = await response.text();
+  } catch {
+    return response.statusText || "Request failed";
+  }
+  if (!text) {
+    return response.statusText || "Request failed";
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.message === "string" && parsed.message.trim()) {
+      return parsed.message;
+    }
+  } catch {}
+  return text;
+}
+async function probeApiVersion() {
+  try {
+    const response = await dockerFetch(`${DOCKER_HOST}/version`, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json();
+    if (typeof payload.ApiVersion !== "string" || !payload.ApiVersion.trim()) {
+      return null;
+    }
+    return selectApiVersion(payload.ApiVersion);
+  } catch {
+    return null;
+  }
+}
+async function resolveApiVersion() {
+  if (cachedApiVersion) {
+    return cachedApiVersion;
+  }
+  if (!resolvingApiVersion) {
+    resolvingApiVersion = probeApiVersion().then((apiVersion) => {
+      if (apiVersion) {
+        cachedApiVersion = apiVersion;
+        return apiVersion;
+      }
+      return CLIENT_API_VERSION;
+    }).finally(() => {
+      resolvingApiVersion = null;
+    });
+  }
+  return resolvingApiVersion;
+}
+async function dockerRequest(options) {
+  const { method = "GET", path, query, body, headers = {}, allowStatus = [] } = options;
+  const requestHeaders = { ...headers };
+  let requestBody;
+  if (body !== undefined) {
+    if (isRawBody(body)) {
+      requestBody = body;
+    } else {
+      requestBody = JSON.stringify(body);
+      if (!Object.keys(requestHeaders).some((key) => key.toLowerCase() === "content-type")) {
+        requestHeaders["Content-Type"] = "application/json";
+      }
+    }
+  }
+  let response;
+  try {
+    const apiVersion = await resolveApiVersion();
+    response = await dockerFetch(buildUrl(path, query, apiVersion), {
+      method,
+      headers: requestHeaders,
+      body: requestBody
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown Docker transport error";
+    throw new DockerError(0, message);
+  }
+  if (!response.ok && !allowStatus.includes(response.status)) {
+    throw new DockerError(response.status, await readDockerErrorMessage(response));
+  }
+  return response;
+}
+async function dockerJSON(options) {
+  const response = await dockerRequest(options);
+  return await response.json();
+}
+
+// ../../packages/core/src/primitives/create.ts
+async function create(options = {}) {
+  const { name, image = "agent-sandbox" } = options;
+  const createResponse = await dockerJSON({
+    method: "POST",
+    path: "/containers/create",
+    query: name ? { name } : undefined,
+    body: {
+      Image: image,
+      Labels: {
+        "agent-sandbox": "true"
+      }
+    }
+  });
+  await dockerRequest({
+    method: "POST",
+    path: `/containers/${createResponse.Id}/start`
+  });
+  return {
+    sandboxId: createResponse.Id.slice(0, 12)
+  };
+}
+// ../../packages/core/src/primitives/delete.ts
+function remapContainerNotFound(error, sandboxId) {
+  if (error instanceof DockerError && error.status === 404) {
+    throw new ContainerNotFoundError(sandboxId);
+  }
+  throw error;
+}
+async function deleteContainer(options) {
+  const { sandboxId } = options;
+  try {
+    await dockerRequest({
+      method: "POST",
+      path: `/containers/${sandboxId}/stop`,
+      allowStatus: [304]
+    });
+  } catch (error) {
+    remapContainerNotFound(error, sandboxId);
+  }
+  try {
+    await dockerRequest({
+      method: "DELETE",
+      path: `/containers/${sandboxId}`
+    });
+  } catch (error) {
+    remapContainerNotFound(error, sandboxId);
+  }
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/download.ts
+import path2 from "path";
+
+// ../../packages/core/src/archive.ts
+import { tmpdir } from "os";
+import path from "path";
+import { mkdir, mkdtemp, readdir, rename, rm, stat } from "fs/promises";
+function ensureAbsoluteHostPath(targetPath) {
+  if (!path.isAbsolute(targetPath)) {
+    throw new SandboxError(`Host path must be absolute: ${targetPath}`);
+  }
+}
+async function ensurePathExists(targetPath) {
+  try {
+    await stat(targetPath);
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      throw new SandboxError(`Host path does not exist: ${targetPath}`);
+    }
+    if (error instanceof Error) {
+      throw new SandboxError(`Failed to access host path ${targetPath}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+async function ensureTarSuccess(process2, action) {
+  const exitCode = await process2.exited;
+  if (exitCode === 0) {
+    return;
+  }
+  const stderr = process2.stderr;
+  const detail = stderr ? (await new Response(stderr).text()).trim() : "";
+  const suffix = detail ? `: ${detail}` : "";
+  throw new SandboxError(`${action} failed${suffix}`);
+}
+function spawnTar(command, options) {
+  try {
+    return Bun.spawn(command, options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown tar error";
+    throw new SandboxError(`Failed to start tar: ${message}`);
+  }
+}
+async function createTarStream(localPath) {
+  ensureAbsoluteHostPath(localPath);
+  await ensurePathExists(localPath);
+  const directory = path.dirname(localPath);
+  const name = path.basename(localPath);
+  const process2 = spawnTar(["tar", "-C", directory, "-cf", "-", name], {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const stream = process2.stdout;
+  if (!stream) {
+    throw new SandboxError("Tar create failed: tar did not produce an archive stream");
+  }
+  return {
+    stream,
+    complete: () => ensureTarSuccess(process2, "Tar create"),
+    abort: () => {
+      try {
+        process2.kill();
+      } catch {}
+    }
+  };
+}
+async function extractTarStream(stream, localPath) {
+  ensureAbsoluteHostPath(localPath);
+  const targetDirectory = path.dirname(localPath);
+  await mkdir(targetDirectory, { recursive: true });
+  const extractDirectory = await mkdtemp(path.join(tmpdir(), "agent-sandbox-download-"));
+  try {
+    const process2 = spawnTar(["tar", "-C", extractDirectory, "-xf", "-"], {
+      stdin: stream,
+      stdout: "ignore",
+      stderr: "pipe"
+    });
+    await ensureTarSuccess(process2, "Tar extract");
+    const extractedEntries = await readdir(extractDirectory);
+    const [firstEntry] = extractedEntries;
+    if (extractedEntries.length !== 1 || !firstEntry) {
+      throw new SandboxError("Tar extract failed: archive did not contain exactly one top-level entry");
+    }
+    const extractedPath = path.join(extractDirectory, firstEntry);
+    const extractedStats = await stat(extractedPath);
+    if (!extractedStats.isFile() && !extractedStats.isDirectory()) {
+      throw new SandboxError("Tar extract failed: archive did not contain a regular file or directory");
+    }
+    await rm(localPath, { recursive: true, force: true });
+    await rename(extractedPath, localPath);
+  } finally {
+    await rm(extractDirectory, { recursive: true, force: true });
+  }
+}
+
+// ../../packages/core/src/primitives/download.ts
+function ensureAbsoluteContainerPath(targetPath) {
+  if (!path2.posix.isAbsolute(targetPath)) {
+    throw new SandboxError(`Container path must be absolute: ${targetPath}`);
+  }
+}
+async function download(options) {
+  ensureAbsoluteContainerPath(options.remotePath);
+  if (!path2.isAbsolute(options.localPath)) {
+    throw new SandboxError(`Host path must be absolute: ${options.localPath}`);
+  }
+  let response;
+  try {
+    response = await dockerRequest({
+      path: `/containers/${options.sandboxId}/archive`,
+      query: {
+        path: options.remotePath
+      }
+    });
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404 && error.message.includes("No such container")) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  if (!response.body) {
+    throw new SandboxError("Docker archive response was empty");
+  }
+  await extractTarStream(response.body, options.localPath);
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/list.ts
+async function list() {
+  const containers = await dockerJSON({
+    path: "/containers/json",
+    query: {
+      filters: JSON.stringify({
+        label: ["agent-sandbox=true"]
+      })
+    }
+  });
+  const sandboxes = containers.map((container) => {
+    const name = (container.Names[0] ?? "").replace(/^\//, "");
+    return {
+      id: container.Id.slice(0, 12),
+      name,
+      status: container.State,
+      createdAt: new Date(container.Created * 1000).toISOString()
+    };
+  });
+  return { sandboxes };
+}
+// ../../packages/core/src/docker/parse-log.ts
+function parseLogOutput(bytes) {
+  const chunks = [];
+  let totalLength = 0;
+  let offset = 0;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 8) {
+      throw new SandboxError("Malformed Docker log stream");
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset + offset + 4, 4);
+    const payloadLength = view.getUint32(0);
+    const payloadStart = offset + 8;
+    const payloadEnd = payloadStart + payloadLength;
+    if (payloadEnd > bytes.length) {
+      throw new SandboxError("Malformed Docker log stream");
+    }
+    const chunk = bytes.slice(payloadStart, payloadEnd);
+    chunks.push(chunk);
+    totalLength += chunk.length;
+    offset = payloadEnd;
+  }
+  const output = new Uint8Array(totalLength);
+  let writeOffset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, writeOffset);
+    writeOffset += chunk.length;
+  }
+  return new TextDecoder().decode(output);
+}
+
+// ../../packages/core/src/primitives/read.ts
+async function read(options) {
+  const query = {
+    stdout: "1",
+    stderr: "1"
+  };
+  if (options.tail !== undefined) {
+    query.tail = String(options.tail);
+  }
+  let response;
+  try {
+    response = await dockerRequest({
+      path: `/containers/${options.sandboxId}/logs`,
+      query
+    });
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  return {
+    output: parseLogOutput(bytes)
+  };
+}
+// ../../packages/core/src/primitives/upload.ts
+import path3 from "path";
+function ensureAbsoluteContainerPath2(targetPath) {
+  if (!path3.posix.isAbsolute(targetPath)) {
+    throw new SandboxError(`Container path must be absolute: ${targetPath}`);
+  }
+}
+function remapUploadError(error, sandboxId) {
+  if (error instanceof DockerError && error.status === 404) {
+    throw new ContainerNotFoundError(sandboxId);
+  }
+  throw error;
+}
+async function upload(options) {
+  ensureAbsoluteContainerPath2(options.remotePath);
+  const archive = await createTarStream(options.localPath);
+  try {
+    await dockerRequest({
+      method: "PUT",
+      path: `/containers/${options.sandboxId}/archive`,
+      query: {
+        path: path3.posix.dirname(options.remotePath)
+      },
+      body: archive.stream,
+      headers: {
+        "Content-Type": "application/x-tar"
+      }
+    });
+  } catch (error) {
+    archive.abort();
+    remapUploadError(error, options.sandboxId);
+  }
+  await archive.complete();
+  return {
+    ok: true
+  };
+}
+// ../../packages/core/src/primitives/write.ts
+function getDockerMessage(error) {
+  return error.message.replace(/^Docker API error \d+: /, "");
+}
+async function write(options) {
+  const detach = options.detach ?? false;
+  let execId;
+  try {
+    const response = await dockerJSON({
+      method: "POST",
+      path: `/containers/${options.sandboxId}/exec`,
+      body: {
+        Cmd: ["/bin/sh", "-c", options.input],
+        AttachStdout: !detach,
+        AttachStderr: !detach
+      }
+    });
+    execId = response.Id;
+  } catch (error) {
+    if (error instanceof DockerError && error.status === 404) {
+      throw new ContainerNotFoundError(options.sandboxId);
+    }
+    throw error;
+  }
+  if (detach) {
+    try {
+      await dockerRequest({
+        method: "POST",
+        path: `/exec/${execId}/start`,
+        body: {
+          Detach: true
+        }
+      });
+    } catch (error) {
+      if (error instanceof DockerError) {
+        throw new ExecError(getDockerMessage(error));
+      }
+      throw error;
+    }
+    return { ok: true };
+  }
+  let startResponse;
+  try {
+    startResponse = await dockerRequest({
+      method: "POST",
+      path: `/exec/${execId}/start`,
+      body: {
+        Detach: false,
+        Tty: false
+      }
+    });
+  } catch (error) {
+    if (error instanceof DockerError) {
+      throw new ExecError(getDockerMessage(error));
+    }
+    throw error;
+  }
+  const bytes = new Uint8Array(await startResponse.arrayBuffer());
+  const output = parseLogOutput(bytes);
+  const inspect = await dockerJSON({
+    method: "GET",
+    path: `/exec/${execId}/json`
+  });
+  return {
+    ok: true,
+    output,
+    exitCode: inspect.ExitCode
+  };
+}
+// src/commands/utils.ts
+function requireArg(value, name) {
+  if (value === undefined) {
+    throw new Error(`Missing required argument: ${name}`);
+  }
+  return value;
+}
+function readOption(args, index, name) {
+  const value = args[index + 1];
+  if (value === undefined) {
+    throw new Error(`Missing value for option: ${name}`);
+  }
+  return { value, nextIndex: index + 2 };
+}
+
+// src/commands/create.ts
+async function runCreateCommand(args) {
+  let name;
+  let image;
+  for (let i = 0;i < args.length; ) {
+    const arg = args[i];
+    switch (arg) {
+      case "--name": {
+        const option = readOption(args, i, "--name");
+        name = option.value;
+        i = option.nextIndex;
+        break;
+      }
+      case "--image": {
+        const option = readOption(args, i, "--image");
+        image = option.value;
+        i = option.nextIndex;
+        break;
+      }
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  const options = { name, image };
+  const result = await create(options);
+  console.log(result.sandboxId);
+}
+
+// src/commands/delete.ts
+async function runDeleteCommand(args) {
+  const options = {
+    sandboxId: requireArg(args[0], "sandboxId")
+  };
+  const result = await deleteContainer(options);
+  if (!result.ok) {
+    throw new Error("Failed to delete sandbox");
+  }
+}
+
+// src/commands/download.ts
+async function runDownloadCommand(args) {
+  const options = {
+    sandboxId: requireArg(args[0], "sandboxId"),
+    remotePath: requireArg(args[1], "remotePath"),
+    localPath: requireArg(args[2], "localPath")
+  };
+  const result = await download(options);
+  if (!result.ok) {
+    throw new Error("Failed to download from sandbox");
+  }
+}
+
+// src/commands/list.ts
+async function runListCommand() {
+  const result = await list();
+  console.log(JSON.stringify(result.sandboxes, null, 2));
+}
+
+// src/commands/read.ts
+async function runReadCommand(args) {
+  const sandboxId = requireArg(args[0], "sandboxId");
+  let tail;
+  for (let i = 1;i < args.length; ) {
+    const arg = args[i];
+    switch (arg) {
+      case "--tail": {
+        const option = readOption(args, i, "--tail");
+        const parsedTail = Number(option.value);
+        if (!Number.isFinite(parsedTail) || !Number.isInteger(parsedTail) || parsedTail <= 0) {
+          throw new Error(`Invalid value for --tail: expected a positive integer, got "${option.value}"`);
+        }
+        tail = parsedTail;
+        i = option.nextIndex;
+        break;
+      }
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  const options = { sandboxId, tail };
+  const result = await read(options);
+  process.stdout.write(result.output);
+}
+
+// src/commands/upload.ts
+async function runUploadCommand(args) {
+  const options = {
+    sandboxId: requireArg(args[0], "sandboxId"),
+    localPath: requireArg(args[1], "localPath"),
+    remotePath: requireArg(args[2], "remotePath")
+  };
+  const result = await upload(options);
+  if (!result.ok) {
+    throw new Error("Failed to upload to sandbox");
+  }
+}
+
+// src/commands/write.ts
+async function runWriteCommand(args) {
+  let detach = false;
+  const positional = [];
+  for (const arg of args) {
+    if (arg === "--detach") {
+      detach = true;
+    } else {
+      positional.push(arg);
+    }
+  }
+  const options = {
+    sandboxId: requireArg(positional[0], "sandboxId"),
+    input: requireArg(positional[1], "input"),
+    detach
+  };
+  const result = await write(options);
+  if (!result.ok) {
+    throw new Error("Failed to write to sandbox");
+  }
+  if (result.output !== undefined) {
+    process.stdout.write(result.output);
+  }
+  if (typeof result.exitCode === "number") {
+    process.exitCode = result.exitCode;
+    if (result.exitCode !== 0) {
+      process.stderr.write(`write command exited with code ${result.exitCode}
+`);
+    }
+  }
+}
+
+// index.ts
+var USAGE = "Usage: agent-sandbox <create|delete|list|read|write|upload|download> ...";
+function printHelp() {
+  console.log(USAGE);
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+    printHelp();
+    return;
+  }
+  switch (command) {
+    case "create": {
+      await runCreateCommand(rest);
+      return;
+    }
+    case "delete": {
+      await runDeleteCommand(rest);
+      return;
+    }
+    case "list": {
+      await runListCommand();
+      return;
+    }
+    case "read": {
+      await runReadCommand(rest);
+      return;
+    }
+    case "write": {
+      await runWriteCommand(rest);
+      return;
+    }
+    case "upload": {
+      await runUploadCommand(rest);
+      return;
+    }
+    case "download": {
+      await runDownloadCommand(rest);
+      return;
+    }
+    default:
+      throw new Error(USAGE);
+  }
+}
+await main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@agent-sandbox/cli",
+  "version": "0.1.1",
+  "description": "CLI to spin up isolated terminal sandboxes for AI agents",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "agent-sandbox": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun run index.ts",
+    "build": "bun build ./index.ts --outfile dist/index.js --target bun",
+    "build:binary": "bun build ./index.ts --compile --minify --bytecode --outfile dist/agent-sandbox"
+  },
+  "devDependencies": {
+    "@agent-sandbox/core": "*",
+    "@types/bun": "^1.3.9"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usamaasfar/agent-sandbox.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/usamaasfar/agent-sandbox#readme",
+  "bugs": {
+    "url": "https://github.com/usamaasfar/agent-sandbox/issues"
+  },
+  "keywords": [
+    "sandbox",
+    "agent",
+    "ai",
+    "terminal",
+    "docker",
+    "cli"
+  ]
+}