Sandboxes Environments

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/sandboxes.ts
• __tests__/commands/sandboxes.test.ts
• CLAUDE.md
• src/bin.ts
• src/client.ts
• __tests__/client.test.ts
• README.md

The Sandboxes module in the Recoup CLI provides developers with the ability to manage isolated execution environments. These environments are typically used for running specific commands or tasks within the Recoup platform infrastructure. The CLI acts as a thin wrapper over the Recoup REST API, facilitating the listing and creation of these sandboxes.

The CLI itself is installed globally within these sandboxes via npm install -g @recoupable/cli, allowing for nested or recursive management of platform resources from within an active environment.
Sources: CLAUDE.md:4-5, src/commands/sandboxes.ts:1-40

Architecture and Command Structure

The sandbox management system is implemented as a subcommand within the main recoup binary. It utilizes the commander library to define a hierarchical command structure.

The diagram shows the command hierarchy from the entry point to the API interaction layer.
Sources: src/bin.ts:10-30, src/commands/sandboxes.ts:5-42

Components and Data Flow

1. Command Discovery: The src/bin.ts file registers sandboxesCommand as a top-level command.
2. Request Handling: Commands use a shared HTTP client (src/client.ts) to perform GET and POST requests to the Recoup API.
3. Authentication: Every request includes an x-api-key header derived from the RECOUP_API_KEY environment variable.
4. Output Processing: Data returned from the API is processed by utility functions in src/output.ts to display either a formatted table or raw JSON.

Sources: src/bin.ts:24, src/client.ts:1-50, CLAUDE.md:14-17, src/commands/sandboxes.ts:2-4

Sandbox Management Operations

Listing Sandboxes

The list command retrieves all sandboxes associated with the current account. By default, it displays a table containing the ID, status, and creation timestamp of each sandbox.

Field	Description	Source
sandboxId	Unique identifier for the environment	src/commands/sandboxes.ts:17
sandboxStatus	Current state (e.g., 'running')	src/commands/sandboxes.ts:18
createdAt	ISO timestamp of creation	src/commands/sandboxes.ts:19

The sequence of events when a user requests a list of active environments.
Sources: src/commands/sandboxes.ts:5-24, __tests__/commands/sandboxes.test.ts:32-55

Creating Sandboxes

The create command triggers the provisioning of a new sandbox. Users can optionally specify a command to be executed immediately upon startup using the --command flag.

API Endpoint: POST /api/sandboxes
Request Body:

• command (optional): A string containing the shell command to execute.

Sources: src/commands/sandboxes.ts:26-46, __tests__/commands/sandboxes.test.ts:57-101

Configuration and Global Flags

Sandbox commands respect the global CLI configuration and flags.

Flag	Type	Description
--json	Boolean	Returns raw JSON instead of formatted text/tables.
--command	String	(Create only) Specifies the initial command to run.

The API interaction is governed by the following environment variables:

• RECOUP_API_KEY: Required for authentication via x-api-key header.
• RECOUP_API_URL: Optional override for the base API URL (defaults to https://recoup-api.vercel.app).

Sources: src/commands/sandboxes.ts:8, 29, README.md:41-45, CLAUDE.md:14-22

Implementation Details

The sandboxesCommand is exported as a configured commander.Command object. It encapsulates the logic for both list and create subcommands, including error handling through a standardized printError utility that exits the process on failure.

// Example of sandbox creation logic
const data = await post("/api/sandboxes", body);
const sandboxes = (data.sandboxes as Record<string, unknown>[]) || [];

if (opts.json) {
  printJson(sandboxes);
} else {
  for (const sb of sandboxes) {
    console.log(`Created sandbox: ${sb.sandboxId}`);
  }
}

Sources: src/commands/sandboxes.ts:37-46, __tests__/client.test.ts:85-105

Conclusion

The Sandboxes Environment module serves as a critical interface for managing remote compute resources on the Recoup platform. By providing a streamlined CLI experience for listing and creating environments, it enables developers to automate workflows and execute commands within isolated, platform-managed contexts.