Persistence

A Computer saves part of its state and restores it when you start it again: its cookies, localStorage, passkeys and learned skills. Its session files are temporary. Each kind of state has its own rule, listed below; there is no blanket promise for every file.

What persists

Saves cover cookies, learned skills and passkeys, and localStorage is saved separately when the browser stops, which a graceful stop guarantees. Session files are never saved. Artifacts belong to the active runtime; save important outputs in your own storage.

What each lifecycle step does

computer.stop: save, then release

Stop saves the Computer's state and then releases the runtime. The Computer stops taking new work, saves its cookies and skills, closes the browser to save localStorage, and confirms the encrypted saves before the runtime is released. Start the Computer later with its id, state key and capture keypair to restore what was saved. Stop doesn't keep sessions, work directories, HOME, downloads or artifacts.

In the Ruby SDK, computer.stop waits up to wait_timeout: seconds and returns true once the runtime is released. If the wait runs out, it returns false and the Stop carries on: call stop again to keep waiting. If the runtime was already gone, stop returns true, which confirms the release but not a final save.

If the save fails, stop raises PineSandbox::StopSaveError and keeps the runtime. The browser may already be closed by then. Call stop again when the error's retryable? is true. Otherwise client.recover_computer (coming soon in the next SDK releases) releases that runtime and starts the Computer from its last save, losing anything not yet saved.

computer.kill: release without waiting for a save

Kill releases the runtime without waiting for a save. Use it when something has gone wrong and the runtime has to go. Pine still tries a final save as the runtime shuts down, but doesn't confirm it, so a later start may restore only what was saved before: the latest periodic save of cookies and skills, and an older localStorage. Kill doesn't wait, and returns false if the release request failed.

computer.checkpoint: save right away

Checkpoint saves cookies and learned skills without stopping the Computer, and returns once the save is stored. It doesn't save localStorage or session files. If nothing changed since the last save, it stores nothing and reports skipped.

computer.pause and computer.resume: keep everything in memory

Coming soon. computer.pause and computer.resume arrive in the next Ruby and Go SDK releases.

For projects with Pause enabled. Pause captures the Computer's whole memory, so the runtime, its sessions and their state all survive, and resume brings them back. Both wait for the operation to finish (timeout:, 360 seconds by default). A paused Computer still reaches its expiry, and a resume that fails never starts a fresh Computer in its place.

If the Computer's services restart

The browser profile and the session files stay. Session secrets are cleared and any turn in progress ends. Send the secrets again before you retry work that needs them.

If the browser restarts

The session's tabs close. Its next window opens on a blank page, and its other tabs are not restored.

Starting on a new runtime

A Computer can move to a new runtime after maintenance, a failure or a stop. Starting it needs its id, state key and capture keypairs; the SDK uses them to restore the saved cookies, skills, passkeys and localStorage. To keep using a runtime that's still running instead, see Reuse a running Computer.

Cookies and localStorage are saved on different schedules, so one can be newer than the other. A new runtime doesn't restore tabs, sessions, work directories, artifacts, downloads, HOME or session secrets. Create a new session and send it its inputs and secrets again.

Beta expectations

Treat browser recovery as best effort during the beta. Don't make a browser save your only copy of application data. Download important artifacts to your own storage before you stop the Computer: files in the work directory, HOME and the artifact store last only as long as the runtime.

The keys your backend holds

Keep each Computer's state key and capture private keys on your backend.

PineSandbox::Computer.generate_credentials creates them with the Computer's id: a 32-byte state key and a capture keypair. Save them before you create the Computer; Getting started shows how. Every save is sealed to your capture public key. On each attach, the SDK uses your pk_ to get short-lived credentials for that one runtime, and uses your private key to let the new runtime restore the saved state. Your private keys never leave your backend.

What this means for you:

• A leaked pk_ alone doesn't expose saved state: restoring it needs the Computer's private keys.
• Pine's storage alone can't expose it either: decrypting a save needs both a key Pine holds and your private key.
• You can start a Computer from any server that has your pk_ and the Computer's id, state key and capture keypair. No key is tied to one machine.

Without these keys the Computer can't be started again and its saved state can't be read, so save them before you create it. The encryption details are internal to Pine and not part of your integration; for the bigger picture, see How a Computer works.

When saves happen

Cookies and learned skills are saved:

• Periodically, every few minutes while the Computer runs, and only when something changed.
• On computer.checkpoint, right away.
• On computer.stop, which also saves localStorage and waits for both saves before the runtime is released.

When a runtime ends without a stop, for example because it expired, Pine tries a final save within a short shutdown window but can't guarantee that it finishes.

API reference

computer.checkpoint, computer.stop and computer.kill are SDK methods. The Computer API reference describes the routes behind them, under Computer Lifecycle and State and Recovery, and the Attach routes the SDK uses to restore state.