Pause and Resume

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

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()

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();

gravixlayer runtime pause "$RT"

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pause" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

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

Resume

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

sandbox.resume()

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

await sandbox.resume();

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

gravixlayer runtime resume "$RT"

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/resume" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

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.

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. To discard a runtime entirely, use terminate, which releases disk as well.

Getting Started

Runtime

Support

Pause

Resume

What is preserved

What changes

Resource accounting

Timing

​Pause

​Resume

​What is preserved

​What changes

​Resource accounting

​Timing

Pause

Resume

What is preserved

What changes

Resource accounting

Timing