> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Sandbox Timeout

> Set or extend the auto-shutdown timeout for a sandbox using the HopX Control Plane API. Configure when sandboxes are automatically destroyed to manage resources and costs. Learn how to use PUT /v1/sandboxes/:id/timeout endpoint to set initial timeouts or extend existing timeouts for long-running tasks. Includes request examples and timeout management.

Set or extend the auto-shutdown timeout for a sandbox. When the timeout expires, the sandbox will be automatically deleted.

## Endpoint

```
PUT /v1/sandboxes/:id/timeout
```

## Request

### Headers

```
Authorization: Bearer $HOPX_API_KEY
Content-Type: application/json
```

### Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `id`      | string | Sandbox ID  |

### Body Parameters

| Parameter         | Type    | Required | Description                              |
| ----------------- | ------- | -------- | ---------------------------------------- |
| `timeout_seconds` | integer | Yes      | New timeout duration in seconds from now |

### Example Request

Set timeout to 1 hour (3600 seconds):

```bash theme={null}
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 3600
  }'
```

Extend timeout by 2 hours:

```bash theme={null}
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 7200
  }'
```

## Response

### Success (200 OK)

```json theme={null}
{
  "id": "sandbox_abc123xyz",
  "timeout_seconds": 3600,
  "expires_at": "2025-01-28T01:00:00Z",
  "request_id": "req_abc123"
}
```

### Response Fields

| Field             | Type    | Description                                 |
| ----------------- | ------- | ------------------------------------------- |
| `id`              | string  | Sandbox ID                                  |
| `timeout_seconds` | integer | New timeout duration in seconds             |
| `expires_at`      | string  | ISO 8601 timestamp when sandbox will expire |
| `request_id`      | string  | Request ID for debugging                    |

## Status Codes

| Code  | Description                  |
| ----- | ---------------------------- |
| `200` | Timeout updated successfully |
| `400` | Invalid timeout value        |
| `401` | Authentication required      |
| `404` | Sandbox not found            |

## Errors

### Invalid Timeout (400)

```json theme={null}
{
  "error": "Invalid timeout value: must be positive",
  "code": "INVALID_REQUEST",
  "request_id": "req_abc123"
}
```

**Cause:** The `timeout_seconds` value is negative, zero, or invalid.

**Fix:** Ensure `timeout_seconds` is a positive integer.

### Sandbox Not Found (404)

```json theme={null}
{
  "error": "Sandbox not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}
```

**Cause:** The sandbox ID doesn't exist or belongs to another organization.

**Fix:** Verify the sandbox ID is correct.

## Important Notes

* **Absolute timeout** - The timeout is set from the current time, not relative to the previous timeout
* **Auto-deletion** - When the timeout expires, the sandbox is automatically deleted
* **Can be extended** - You can extend the timeout multiple times
* **No maximum** - There's no maximum timeout limit (subject to your plan)

## Use Cases

### Extend Timeout for Long-Running Task

```bash theme={null}
# Check current expiration
curl https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.expires_at'

# Extend by 2 hours
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 7200
  }'
```

### Set Timeout on Creation

```bash theme={null}
# Create sandbox with 1 hour timeout
curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "73",
    "timeout_seconds": 3600
  }'
```

### Keep Sandbox Alive Indefinitely

```bash theme={null}
# Set a very long timeout (e.g., 30 days)
curl -X PUT https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/timeout \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 2592000
  }'
```

## Related

* **SDK**: [sandbox.set\_timeout()](/sdk/python/sandbox#set_timeout) - Python SDK method
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Get Sandbox](/api/control-plane/get-sandbox)** - Check current timeout and expiration
* **[Create Sandbox](/api/control-plane/create-sandbox)** - Set timeout on creation
* **[Delete Sandbox](/api/control-plane/delete-sandbox)** - Manually delete before timeout