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

# Auto-Resume

> Pause idle machines and wake them when SDK calls or public traffic arrive.

Auto-resume is for long-lived workspaces, preview servers, and per-user
machines that should not run constantly. Configure the machine to pause on
timeout, then set `auto_resume=True` so public HTTP/WebSocket traffic can wake
it before the request is proxied.

## Configure on create

Choose one control plane for the create call. The snippets below configure the
same timeout and auto-resume behavior. The TypeScript SDK does not expose
`autoResume` or a `pause` timeout policy on create, so configure auto-resume
from the Python SDK, CLI, or HTTP API.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  machine = Machine.create(
      template="base",
      timeout=600,
      on_timeout="pause",
      auto_resume=True,
  )
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine create \
    --template base \
    --timeout 600 \
    --on-timeout pause \
    --auto-resume
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -fsS -X POST "${NULLSPACE_API_URL}/v1/machines" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "template": "base",
      "timeout_ms": 600000,
      "lifecycle": { "on_timeout": "pause" },
      "auto_resume": true
    }'
  ```
</CodeGroup>

<Note>
  `auto_resume=True` requires pause/hibernate timeout behavior. A machine with
  destroy-on-timeout cannot auto-resume because there is no paused state to
  restore.
</Note>

## Wake from public traffic

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
server = machine.commands.run(
    "python3 -m http.server 8080 --bind 0.0.0.0",
    shell=True,
    cwd="/workspace",
    background=True,
)

url = machine.get_url(8080)
print(url)
```

After the machine times out and pauses, an inbound request to the signed HTTP
URL or signed WebSocket URL asks the control plane to resume the paused
machine. When the resume completes within the bounded wait window, the edge
forwards the original request to the resumed execution.

If auto-resume is disabled or the resume cannot complete in time, the public
URL returns `503 Service Unavailable` with `Retry-After: 5`. The JSON body
includes a stable `code`, `retryable`, and `suggested_action`. Disabled policy
responses use `machine_paused_auto_resume_disabled` with `retryable: false`.
Timeout or control-plane availability failures are retryable and can be retried
after the `Retry-After` delay.

## Wake from SDK calls

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Machine

machine = Machine.connect("mch_...")
result = machine.commands.run("echo resumed", shell=True)
print(result.stdout)
```

`Machine.connect(id)` is an explicit reconnect operation. If `id` points at a
paused machine alias, `connect()` resumes its snapshot and returns a running
machine handle.

Use `Machine.get_info_by_id(id)` when you need a read-only status check that
does not wake a paused machine.

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
info = Machine.get_info_by_id("mch_...")
print(info.status, info.snapshot_id)
```

## Paused aliases and new IDs

Resume creates a new running machine execution. The original paused machine ID
is kept as an alias so reconnect and traffic-triggered wakeups can find the
latest resumed target. Code that persists machine IDs should update its stored
ID after `connect()` or resume returns a new handle.

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
original_id = machine.id
snapshot = machine.pause()

resumed = Machine.connect(original_id)
print(original_id, resumed.id)
```

Shared volume attachments are remounted when a machine resumes. VM memory and
mutable rootfs state still depend on snapshot compatibility with the runtime
host and kernel.

## Common patterns

| Pattern                                          | Recommended configuration                       |
| ------------------------------------------------ | ----------------------------------------------- |
| Preview server that should wake on a browser hit | `on_timeout="pause", auto_resume=True`          |
| Per-user workspace stored by machine ID          | Store the latest `machine.id` after `connect()` |
| Background agent task with explicit scheduler    | Use `Machine.connect(id)` before each task      |
| Disposable CI-style run                          | Keep default destroy-on-timeout behavior        |

## Related

* [Preview URLs](../networking/preview-urls)
* [Persistence](./persistence)
* [Metrics and timeouts](./metrics-timeouts)
* [Lifecycle events](../observability/lifecycle-events)