> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/auto-pause-and-resume.md).

# Auto Pause and Resume

![Timeline: a sandbox is working and billed, goes quiet for the idle window, pauses with memory and disk saved and no compute billed, then the next call wakes it and billing resumes.](https://1980728309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqquJG2zKVZ5l1Sd5aQy%2Fuploads%2Fgit-blob-4b40d230f7b896ab964b405b6383ef9166dd0e04%2Fpause.jpg?alt=media)

An agent spends most of its life not using its computer. It plans, waits for a model response, or waits for a human to approve the next step. A sandbox doesn't charge for that time. When it has been idle for a window you choose, it pauses itself, and the next call wakes it.

## How It Works

1. **Working.** Every API or MCP call into the sandbox, such as an exec, a file read or a process start, counts as activity and resets the idle timer.
2. **Idle.** No activity for the idle window. The default is 15 minutes.
3. **Paused.** The sandbox's process memory and filesystem are checkpointed, and its compute stops. **Compute billing stops while it is paused.** The sandbox only pauses once that checkpoint is saved. If the checkpoint doesn't finish, the sandbox stays running and billed, and the pause is tried again later.
4. **Woken.** The next MCP or REST API call to the sandbox is held while it resumes, then goes through. With the SDKs, call `resume()` before running more commands. Either way, processes, open files and installed packages are exactly as they were.

A paused sandbox isn't a cold one. Because memory is checkpointed, a dev server that was listening is still listening after it wakes, and a Python kernel still holds its variables.

## Set the Idle Window

Pass `lifecycle` when you create the sandbox:

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
const sandbox = await neev.sandboxes.create({
  name: "review-bot",
  lifecycle: {
    idle_timeout_seconds: 300, // pause after 5 idle minutes
    on_idle: "pause",          // the default; "delete" removes it instead
  },
});
```

{% endtab %}

{% tab title="Python" %}

```python
sandbox = client.sandboxes.create({
    "name": "review-bot",
    "lifecycle": {
        "idle_timeout_seconds": 300,  # pause after 5 idle minutes
        "on_idle": "pause",           # the default; "delete" removes it instead
    },
})
```

{% endtab %}
{% endtabs %}

| Field                      | What it does                                                                                     | If you omit it                   |
| -------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------- |
| `idle_timeout_seconds`     | Act on the sandbox after this many seconds with no activity. `0` turns the idle limit off        | The account default (15 minutes) |
| `max_lifetime_seconds`     | Act on the sandbox this many seconds after creation, however busy it is. `0` turns the limit off | No lifetime limit                |
| `paused_retention_seconds` | Delete a sandbox that has stayed paused this long. `0` keeps it paused indefinitely              | Kept paused indefinitely         |
| `on_idle`                  | `pause` keeps state so the sandbox can be resumed. `delete` removes the sandbox and its data     | `pause`                          |

`on_idle` applies to both the idle limit and the maximum lifetime.

The sandbox record tells you when each limit will next apply. `idle_expires_at` is when it pauses if nothing happens before then, and `hard_expires_at` is when the lifetime limit applies.

## Change the Window on a Running Sandbox

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
await sandbox.updateTimeout({ idle_timeout_seconds: 1800 });
```

{% endtab %}

{% tab title="Python" %}

```python
sandbox.update_timeout({"idle_timeout_seconds": 1800})
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X PUT "https://api.ai.neevcloud.com/agent/api/v1beta1/orgs/$NEEV_ORG_ID/projects/$NEEV_PROJECT_ID/sandboxes/$SANDBOX_ID/timeout" \
  -H "Authorization: Bearer $NEEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idle_timeout_seconds": 1800}'
```

{% endtab %}
{% endtabs %}

Fields you omit stay as they are.

## Keep a Sandbox Awake

A sandbox already counts a process started with `processes` (or `process_start` over MCP), an open exec stream and a live terminal as activity, so a background build run that way keeps it awake without any help. Two kinds of work don't count: a person clicking around a preview URL, and a command detached from any request, for example `nohup ... &` inside an exec. For those, call `keepalive` to reset the idle timer. Once per agent turn is a good rhythm.

{% tabs %}
{% tab title="TypeScript / JavaScript" %}

```typescript
await sandbox.keepalive();
```

{% endtab %}

{% tab title="Python" %}

```python
sandbox.keepalive()
```

{% endtab %}
{% endtabs %}

Over MCP, the same thing is the `keepalive_sandbox` tool.

## What Wakes a Paused Sandbox

| Traffic                                                                                                      | Wakes it?                                       |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| REST runtime API calls (exec, files, processes, terminal, SSH) made with an API key                          | Yes. The call is held, then served              |
| SDK calls (`exec`, `files`, `processes`)                                                                     | No. The SDK asks you to call `resume()` first   |
| [Sandbox MCP Server](/agentic-studio/overview/integrations-and-support/sandbox-mcp-server.md) tool calls     | Yes                                             |
| An explicit `resume` (console button, SDK, API or `resume_sandbox` tool)                                     | Yes                                             |
| A [preview URL](/agentic-studio/overview/development-and-connectivity/exposing-ports.md) opened in a browser | No. The visitor sees that the preview is paused |
| The console's built-in terminal                                                                              | No. Resume the sandbox from the console first   |

A call is held for up to about a minute while the sandbox wakes. Resume is usually much faster than that. If too many calls pile up against one waking sandbox, the extra ones get `429 Too Many Requests` with a `Retry-After` header. Retry after that delay.

## Pausing Yourself

You can still pause a sandbox the moment you know you're done, from the console's **Pause** button, `sandbox.pause()`, or the `pause_sandbox` tool. See [Create, Pause, and Delete Sandboxes](/agentic-studio/overview/sandbox-management/create-pause-delete-sandboxes.md#pause-a-sandbox).

## Good Defaults

| Workload                                           | Suggested setting                                                                                                                                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Coding agent that waits on a human between steps   | `idle_timeout_seconds: 300`, `on_idle: "pause"`                                                                                                                          |
| One-shot code execution (evaluate and throw away)  | `idle_timeout_seconds: 120`, `on_idle: "delete"`                                                                                                                         |
| Preview a person is reviewing in a browser         | Raise `idle_timeout_seconds`, or call `keepalive` while they're active                                                                                                   |
| Long-running background job with no incoming calls | Start it with `processes` so it counts as activity, keep a normal `idle_timeout_seconds`, and add a `max_lifetime_seconds` cap. The sandbox pauses once the job finishes |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-management/auto-pause-and-resume.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.