Sandbox

Krutrim Cloud Sandbox provides isolated, ephemeral cloud environments for running code, testing applications, executing workloads, and supporting autonomous AI agentic workflows.

Sandboxes can be created and managed through the Krutrim Cloud Console, Python/TypeScript SDKs, direct REST API, MCP Server, and the native Hermes Agent plugin.

Python SDK for Sandbox

Sandbox is part of the Core Infrastructure SDK. Install the PyPI package krutrim-client:

pip install krutrim-client

Import the client from the Python module krutrim_client:

from krutrim_client import KrutrimClient

The package name uses a hyphen (krutrim-client); the import module uses an underscore (krutrim_client). The separate krutrim-cloud package is for AI Studio/model APIs and does not provide Sandbox APIs.

For SDK selection, installation and client setup, see the Core Infrastructure SDK guide. Do not substitute AI Studio SDK examples for Sandbox calls.

What You Can Do

Isolated Compute: Spin up secure gVisor-isolated containers with dedicated CPU and memory in seconds.
Dedicated Workspace: A persistent workspace directory at /app for code, artifacts, and execution state.
Command Execution: Execute synchronous bash commands with stdout/stderr capture and configurable timeouts (1–270s).
Full Filesystem Management: Upload, download, list, stat, move, and delete files and directories via Base64 wire protocol.
Port Forwarding & Web Previews: Forward container ports (1024–65535) to public HTTPS URLs to preview web apps.
Environment Configuration: Pass runtime environment variables to container processes.
Lifecycle & TTL Management: Automated resource reclamation with configurable TTL from 1 minute to 7 days.

Create a Sandbox

The currently active region is In-Bangalore-1.

Using the Console

You can create a Sandbox from the Krutrim Cloud Console by providing the required configuration:

Setting

What to Configure

Constraints & Rules

Sandbox Name

Specify a unique identifier for your Sandbox.

1–28 characters, lowercase letters, digits, and hyphens only. Must start with a letter and end with a letter/digit. (Capped at 28 chars so the platform-generated DNS subdomain fits within 63 characters).

Region

Select the deployment region.

Currently In-Bangalore-1.

Compute Flavor

Select CPU and RAM configuration.

sandbox-nano to sandbox-x-large.

Expiry (TTL)

Maximum lifetime before auto-deletion.

60s to 604,800s (1 min to 7 days). Defaults to 3,600s (1 hour) if omitted.

Environment Variables

Key-value pairs passed into the container.

String-to-string dictionary.

Compute Configuration

Choose a compute flavor based on your workload's CPU and memory requirements. All flavors include 20 GB of ephemeral disk storage.

Flavor ID

vCPU

RAM

Ephemeral Disk

Hourly Pricing

Recommended Workload

sandbox-nano

0.25

0.5 GiB

20 GB

₹0.50 / hr

Micro-benchmarks, basic scripts, shell tests

sandbox-small

0.50

1.0 GiB

20 GB

₹1.00 / hr

Python scripting, code interpreters, small CLI tools

sandbox-medium

1.00

2.0 GiB

20 GB

₹2.00 / hr

Web servers (FastAPI/Express), data parsing, test runners

sandbox-large

2.00

4.0 GiB

20 GB

₹4.00 / hr

Multi-threaded builds, large dependency installations

sandbox-x-large

4.00

8.0 GiB

20 GB

₹8.00 / hr

Heavy compilation, data science, pandas/numpy pipelines

Work in Your Sandbox

1. Workspace

Each Sandbox provides a clean, writable workspace root at:

/app

All commands and filesystem operations default to /app. Use /app (or /app/project) to store your source code, virtual environments, configuration files, and build artifacts.

2. Run Commands

You can execute bash commands synchronously within an active Sandbox via the API, SDK, or MCP.

POST /omni/sandbox/v1/sandbox/{sandbox_id}/commands

Capabilities & Features:

Real-time Output Capture: Returns stdout, stderr, and process exitCode.
Execution Timeout: Configurable timeoutSeconds between 1 and 270 seconds (default: 30s).
Truncation Flags: stdoutTruncated and stderrTruncated indicate if output exceeded buffer limits.

Common Use Cases:

Running application scripts (python3 main.py, npm start)
Installing dependencies (pip install -r requirements.txt, npm install)
Running test suites (pytest, npm test)
Compiling binaries and processing datasets

3. Manage Files

The Sandbox data plane provides 7 core filesystem operations:

Upload File (POST /files): Upload files by providing the remote path and Base64-encoded file contents (data_base64).
Download File (GET /files?path=...): Download file contents. For binary files (images, PDFs, tarballs), pass format=bytes to receive raw Base64 data.
List Directory (GET /directory?path=...): List directory contents with file metadata (size, permissions, modified timestamp, is_dir).
File/Directory Stat (GET /stat?path=...): Retrieve metadata for a single path without reading the entire file.
Create Directory (POST /directory): Recursively create remote directories (mkdir -p).
Move / Rename (POST /move): Relocate or rename files and directories (source $\rightarrow$ destination).
Delete Path (DELETE /files?path=...): Delete a file or recursively remove an entire directory tree.

4. Port Forwarding & Web Previews

You can expose internal TCP/HTTP services running inside the Sandbox (e.g., React on 3000, Vite on 5173, FastAPI/Streamlit on 8000) to the public internet:

Open Port (POST /ports): Forward a container port (allowed range: 1024 to 65535). Returns a public HTTPS preview URL.
List Ports (GET /ports): List all currently forwarded ports and their public endpoints.
Close Port (DELETE /ports/{port}): Close a port mapping and revoke public access.

5. Environment Variables

Environment variables can be configured when creating a Sandbox. They are injected into container subshells and applications, making it easy to configure API endpoints, runtime modes, and application flags.

6. Ephemeral Storage Notice

[!WARNING] Sandbox storage is ephemeral. When a Sandbox expires or is deleted, all files, installed packages, and generated artifacts in /app are permanently deleted. If data or artifacts must persist, download them via the Filesystem API or store them in an external storage service (e.g. Krutrim Cloud Object Storage) before the TTL expires.

Sandbox Lifecycle

A Sandbox progresses through the following deterministic lifecycle states:

┌─────────────┐       ┌────────────┐       ┌─────────────┐       ┌───────────┐
│  deploying  │ ───>  │   active   │ ───>  │   deleting  │ ───>  │  HTTP 404 │
└─────────────┘       └────────────┘       └─────────────┘       └───────────┘
       │
       └───> ┌───────────────┐
             │ failed_deploy │
             └───────────────┘

State

Description

Next Actions

deploying

The container is provisioning and booting the runtime daemon.

Poll GET /sandbox/{id} until status changes.

active

The Sandbox is ready to accept commands and file operations.

Execute workloads, transfer files, forward ports.

deleting

The Sandbox is being torn down and resources reclaimed.

Wait for completion (verified by HTTP 404).

failed_deploy

Container provisioning timed out or failed to initialize.

Inspect error details; delete and recreate.

TTL (Sandbox Lifetime)

The TTL is an absolute lifetime starting from the moment the Sandbox reaches active status.

[!IMPORTANT] TTL is NOT an idle timeout. Making API calls, running commands, or transferring files does not reset the TTL timer.

TTL Boundaries:

Minimum TTL: 60 seconds (1 minute).
Maximum TTL: 604,800 seconds (7 days).
Default TTL: 3,600 seconds (1 hour) if omitted.

Extending Lifetime:

You can extend an active Sandbox's lifetime at any time by calling the Reset TTL endpoint:

POST /omni/sandbox/v1/sandbox/{sandbox_id}/reset-ttl

Direct REST API Quickstart

1. Create a Sandbox

curl -X POST "https://cloud.olakrutrim.com/omni/sandbox/v1/sandbox" \
  -H "Authorization: Bearer $KRUTRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxName": "my-app-sandbox",
    "flavorName": "sandbox-small",
    "region": "In-Bangalore-1",
    "ttlSeconds": 3600
  }'

2. Poll Status

curl -X GET "https://cloud.olakrutrim.com/omni/sandbox/v1/sandbox/{sandbox_id}" \
  -H "Authorization: Bearer $KRUTRIM_API_KEY"

3. Execute a Command

curl -X POST "https://cloud.olakrutrim.com/omni/sandbox/v1/sandbox/{sandbox_id}/commands" \
  -H "Authorization: Bearer $KRUTRIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cmd": "python3 --version",
    "timeoutSeconds": 30,
    "cwd": "/app"
  }'

4. Delete a Sandbox

curl -X DELETE "https://cloud.olakrutrim.com/omni/sandbox/v1/sandbox/{sandbox_id}" \
  -H "Authorization: Bearer $KRUTRIM_API_KEY"

Best Practices

Select the Right Flavor: Use sandbox-small for general scripts and agents; scale up to sandbox-large or sandbox-x-large for heavy builds or data analysis.
Set Intentional TTLs: Always pass explicit ttlSeconds tailored to your task duration to prevent accidental compute charges.
Persist Critical Data: Download logs, datasets, and generated artifacts before deleting the Sandbox or before the TTL expires.
Explicit Teardown: Call DELETE /sandbox/{id} immediately upon task completion to release resources and stop billing.

Last updated 6 days ago

Was this helpful?