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

# Pause and Resume

> Suspend a runtime to disk to release its host memory, then restore it exactly as it was

Pausing a runtime snapshots its memory to disk and shuts the virtual machine process down,
so the host reclaims the guest's RAM. Resuming relaunches the machine and loads that memory
image back.

This is not a stop and re-create. The runtime comes back as the exact same machine: every
process is still running, every open file is still open, every variable in a REPL still
holds its value, and the runtime keeps its IP address, hostname and disk.

Use it when an agent session goes idle. A paused runtime holds no host memory and stops
consuming CPU and RAM quota, but keeps its full state ready to continue.

## Pause

`POST /v1/agents/runtime/{runtime_id}/pause`

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  ctx = client.runtime.create_context(sandbox.runtime_id)
  client.runtime.run_code(sandbox.runtime_id, code="counter = 41", context_id=ctx.context_id)

  sandbox.pause()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  const ctx = await sandbox.createContext();
  await sandbox.runCode('counter = 41', { contextId: ctx.contextId });

  await sandbox.pause();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime pause "$RT"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pause" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

Pausing is idempotent: pausing an already paused runtime succeeds and does nothing.

## Resume

`POST /v1/agents/runtime/{runtime_id}/resume`

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  sandbox.resume()

  result = client.runtime.run_code(
      sandbox.runtime_id,
      code="print(counter + 1)",
      context_id=ctx.context_id,
  )
  print(result.text)  # 42
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await sandbox.resume();

  const result = await sandbox.runCode('counter + 1', { contextId: ctx.contextId });
  console.log(result.text); // 42
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer runtime resume "$RT"
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/resume" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

## What is preserved

| Preserved          | Notes                                                        |
| ------------------ | ------------------------------------------------------------ |
| Process state      | Every process resumes at the instruction it was suspended on |
| Execution contexts | REPL variables, imported modules, loaded models in memory    |
| Filesystem         | The runtime's disk is untouched by pause                     |
| Network identity   | Same private IP address, hostname and network namespace      |
| PTY sessions       | Sessions and their scrollback survive the pause              |

## What changes

* **In-flight network connections are lost.** A TCP connection that was open across the
  pause will not survive; the peer sees it drop. Have long lived clients reconnect.
* **The guest clock is corrected on resume.** The guest wakes believing it is still the
  instant it was paused, so the platform steps `CLOCK_REALTIME` forward before the runtime
  serves traffic. Wall clock reads are correct after resume, but a monotonic timer started
  before the pause does not count the paused interval.
* **Timers and scheduled work fire late.** A `sleep` or cron job that should have fired
  during the pause fires shortly after resume instead.

## Resource accounting

| Resource    | While paused                                                     |
| ----------- | ---------------------------------------------------------------- |
| Host memory | Released. The memory image lives on disk                         |
| vCPU quota  | Released                                                         |
| RAM quota   | Released                                                         |
| Disk quota  | Still held. The runtime's disk and memory image remain allocated |

Because resuming re-acquires CPU and RAM quota, a resume can be rejected if your account has
since allocated that capacity elsewhere. It is also rejected if the wallet balance is
insufficient. Handle both when resuming after a long idle period.

## Timing

Pause has to write the guest's memory to disk, so it takes longer for runtimes with a large
working set. Resume loads pages back on demand rather than all at once, so the runtime
becomes responsive quickly and host memory grows back only as the guest touches it.

<Note>
  Pause is for idle sessions you intend to continue on the **same** runtime. To save a
  named checkpoint and start **new** runtimes from it, use
  [snapshots](/documentation/agentruntime/snapshots/overview). To discard a runtime
  entirely, use [terminate](/documentation/agentruntime/sandbox-management/terminate-sandbox),
  which releases disk as well.
</Note>