Skip to main content
Sign in to your app once, save the device state as you release the session, and start every later session from that state. The app is installed and signed in when the new session starts, so tests and agents skip the sign-in flow. It works on iOS Simulator and Android Emulator sessions through the CLI, the TypeScript SDK, and the REST API.

What a state holds

A state does not hold system permission grants, the simulated location, the appearance, or other device settings. Set those again after a restore. Android Keystore keys and AccountManager accounts live outside package data. An app that keeps its session there can ask the user to sign in again after a restore.

Limits

  • A state is kept for 30 days after it is saved. A restore does not extend that time. Read expiresAt to see when it expires.
  • A state is capped at 1 GiB compressed. A larger save fails with too_large.
  • A state restores only onto the platform it was saved on.
  • A state belongs to the principal that saved it: the user or API key, in that account. Another API key in the same organization cannot read, restore, or delete it. Save the state with the same key that CI or the agent uses to restore it.

Sign in once, then reuse the state

Without --wait, delete --save-state prints the stateId as soon as the save starts. The state is pending until the host has uploaded it. Check it with:
Save a new state when your app’s sign-in expires, or after you install a new build that changes its data format.

Use the TypeScript SDK

Use cloud.android the same way. cloud.states.delete(stateId) deletes a state and is idempotent.

Use the REST API

Replace ios with android for an emulator session.

When a restore does not happen

A create with restoreState always returns a session. When the state cannot be restored, the session starts from a clean device and stateRestore says why. The CLI prints a warning to stderr in that case.

When a save fails

delete --save-state releases the session in all cases. The save itself fails when savedState.status is failed or the state later becomes failed: The CLI exits with status 1 when the save fails, and prints the error code.