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 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
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):
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
}'
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)
{
"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)
{
"error": "Invalid timeout value: must be positive",
"code": "INVALID_REQUEST",
"request_id": "req_abc123"
}
timeout_seconds value is negative, zero, or invalid.
Fix: Ensure timeout_seconds is a positive integer.
Sandbox Not Found (404)
{
"error": "Sandbox not found",
"code": "RESOURCE_NOT_FOUND",
"request_id": "req_abc123"
}
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
# 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
# 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
# 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
}'
Next Steps
