> For the complete documentation index, see [llms.txt](https://docs.cloud.olakrutrim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/sandbox/mcp-for-sandbox.md).

# MCP for Sandbox

Create a Krutrim Cloud Sandbox from your AI client with API-key authentication, reviewed inputs, and explicit confirmation.

Use a connected AI client to discover Sandbox configurations, review a creation request, and provision an isolated Krutrim Cloud environment through MCP. This creates a real Cloud resource; review pricing and lifetime before approving it.

## Before you begin

* Complete the installation, API-key setup, and client connection in the [MCP Overview](/mcp/overview.md).
* Use an account with permission to create Sandboxes. Configure the raw API key privately as `KRUTRIM_API_KEY`, without a `Bearer` prefix. Never paste the key into an agent prompt.
* Choose one of the currently available Sandbox regions: `In-Bangalore-1` or `In-Hyderabad-1`.
* `KRUTRIM_MCP_READ_ONLY=true` blocks creation and other mutations. Keep it enabled for discovery-only sessions; change it only when you intentionally authorize a writable workflow.

## Create your Sandbox

{% stepper %}
{% step %}

### Discover configurations

Ask the client to call `list_sandbox_flavors` with your selected region (`region="In-Bangalore-1"` or `region="In-Hyderabad-1"`) and `list_sandbox_templates` with no arguments. Also use `list_sandboxes` in the same region to check for an existing Sandbox with your intended name. For Hyderabad (`In-Hyderabad-1`), use the exact flavor name returned by `list_sandbox_flavors`, such as `sandbox-small-hyd`.

Review returned compute resources, pricing, flavor status, and availability. These are a live snapshot, not a capacity reservation; missing availability means unknown.
{% endstep %}

{% step %}

### Choose and review the inputs

* `sandbox_name`: 1–28 lowercase letters, digits, or hyphens. Start with a letter and end with a letter or digit.
* `flavor_name`: use the exact listed name, not a flavor ID. Creation rechecks that the live flavor status is active.
* Choose exactly one of `template_name` (exact listed name) or `template_id` (listed positive integer, not a quoted string). No template is inferred.
* `ttl_seconds`: optional integer from 60 to 604800 seconds **(1 minute–7 days)**. Omit it, or pass null, to use the backend default of **one hour**—not an unlimited lifetime.

Review the name, region, flavor, template, pricing, and expiry together. Optional `environment_variables` must be a string-to-string object; leave them out when unnecessary and do not put secrets in prompts or shared examples.
{% endstep %}

{% step %}

### Approve and create once

After you explicitly approve the reviewed inputs, the client calls `create_sandbox` with `confirm=true`. This flag is required by the tool; it is not a substitute for your approval.

Record the exact Sandbox ID or KRN and status returned. The tool attempts creation once; it does not automatically wait for readiness, connect to the Sandbox, or clean it up.
{% endstep %}

{% step %}

### Check readiness separately

Call `describe_sandbox` with the exact returned `sandbox_id` to inspect progress. A `deploying` or accepted response does not mean the environment is ready. Wait for `active` before planning workload execution.

If the status is `failed_deploy`, stop and inspect the failure. Do not silently create a replacement or delete the resource.
{% endstep %}
{% endstepper %}

## Try this in your AI client

This prompt prepares the request and stops before any mutation:

```
Use Krutrim Cloud MCP to prepare a Sandbox named mcp-sandbox-demo in In-Bangalore-1.
List current Sandbox flavors and templates, and check for existing Sandboxes with this name.
Show resources, pricing, flavor status, and availability when returned.
Ask me to choose an exact flavor and template. Use a 3600-second TTL.
Show the proposed creation inputs and wait for my approval.
Do not create, delete, extend lifetime, upload files, or run commands yet.
```

### Example creation arguments

These are MCP tool arguments for `create_sandbox`, not a REST request body. Replace both placeholders with exact values from discovery and execute only after approving the final request.

```json
{
  "sandbox_name": "mcp-sandbox-demo",
  "region": "In-Bangalore-1",
  "flavor_name": "EXACT_LISTED_FLAVOR_NAME",
  "template_name": "EXACT_LISTED_TEMPLATE_NAME",
  "ttl_seconds": 3600,
  "confirm": true
}
```

## After creation

{% hint style="warning" %}
If creation times out, check whether the Sandbox already exists before retrying. Use `list_sandboxes` with the same region and name, inspect all relevant result pages, and use `describe_sandbox` for any returned ID. A timeout does not prove creation failed.
{% endhint %}

Provisioning is separate from execution. Creating a Sandbox through MCP does not automatically move your agent session or its local terminal into that Sandbox. Running commands or transferring files requires an explicit, separately approved workflow targeting the created Sandbox.

Sandbox storage is ephemeral. Preserve required artifacts outside the Sandbox before expiry or deletion. Normal activity does not reset the TTL. Lifetime changes with `set_sandbox_ttl` and deletion with `delete_sandbox` require separate approval and `confirm=true`.

For workspace, storage, and lifecycle details, see [Sandbox](/basics/core-infrastructure/sandbox.md).

For API-key, connection, or tool failures, see [MCP Troubleshooting](/mcp/troubleshooting.md).

## Official references

[Krutrim MCP server on PyPI](https://pypi.org/project/krutrim-mcp-server/#description)

[Krutrim MCP user guide](https://github.com/ola-krutrim/Krutrim-MCP/blob/main/docs/user-guide.md)