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

# Save and restore simulator state (stay signed in)

> Save the apps and app data of an iOS Simulator or Android Emulator session when you release it, and start a later session from that state.

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

| Platform | Saved |
| - | - |
| iOS | Installed apps, their data containers, the project's app groups, and the simulator keychain. Where the host supports it, also the device cookie jar that WebKit sign-ins use. |
| Android | Installed apps and their package data. |

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

```bash iOS theme={null}
# 1. Start a session with your app and sign in by hand, or drive the sign-in.
SESSION_ID=$(runcloud ios create --install ./build/MyApp.tar.gz --json | jq -r '.id')
runcloud ios get "$SESSION_ID" --json | jq -r '.url'   # open the viewer and sign in

# 2. Release it and save the state. --wait returns when the state is ready.
STATE_ID=$(runcloud ios delete "$SESSION_ID" --save-state --wait --json | jq -r '.stateId')

# 3. Every later session starts signed in.
runcloud ios create --restore-state "$STATE_ID" --json | jq '.stateRestore'
```

```bash Android theme={null}
SESSION_ID=$(runcloud android create --install ./app-debug.apk --json | jq -r '.id')
runcloud android get "$SESSION_ID" --json | jq -r '.url'

STATE_ID=$(runcloud android delete "$SESSION_ID" --save-state --wait --json | jq -r '.stateId')

runcloud android create --restore-state "$STATE_ID" --json | jq '.stateRestore'
```

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:

```bash theme={null}
runcloud states get "$STATE_ID" --json          # status: pending, ready, or failed
runcloud states get "$STATE_ID" --wait --json   # wait until it is ready or failed
runcloud states delete "$STATE_ID"              # delete it and every stored copy
```

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

```ts theme={null}
import { Client } from "@run-cloud/sdk";

const cloud = new Client({ apiKey: process.env.RUN_CLOUD_API_KEY! });

const released = await cloud.ios.delete(sessionId, { saveState: true });
if (released.savedState?.status !== "pending") throw new Error(released.savedState?.code);
const stateId = released.savedState.stateId;

// Wait (up to 60 s per call) while the state is still being saved.
let state = await cloud.states.get(stateId, { waitMs: 60_000 });
while (state.status === "pending") state = await cloud.states.get(stateId, { waitMs: 60_000 });

const session = await cloud.ios.create({ restoreState: stateId });
console.log(session.stateRestore); // { stateId, status: "restored", durationMs }
```

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

## Use the REST API

```bash theme={null}
# Save while releasing. The reply carries savedState: { stateId, status: "pending" }.
curl -X DELETE "https://api.run.cloud/run-cloud/ios/$SESSION_ID?saveState=1" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY"

# Read the state; waitMs (max 60000) waits while it is pending.
curl "https://api.run.cloud/run-cloud/states/$STATE_ID?waitMs=60000" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY"

# Restore on create.
curl -X POST "https://api.run.cloud/run-cloud/ios" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"restoreState\": \"$STATE_ID\"}"

# Delete.
curl -X DELETE "https://api.run.cloud/run-cloud/states/$STATE_ID" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY"
```

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.

| `stateRestore.status` | `code` | Meaning |
| - | - | - |
| `restored` | | The apps and their data are on the device. |
| `skipped` | `invalid_state_id` | The id is not a state id. |
| `skipped` | `platform_mismatch` | The state was saved on the other platform. |
| `skipped` | `state_not_ready` | The state is still `pending`, has failed, has expired, or belongs to another principal. |
| `skipped` | `state_unavailable` | Saved state is not available for this session. |
| `failed` | `restore_failed`, `restore_timeout`, `host_unreachable`, … | The host could not apply the state. The session is a clean device. |

## 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`:

| `code` | Meaning |
| - | - |
| `not_running` | The session had no running device to save. |
| `state_unavailable` | Saved state is not available for this account or key. |
| `host_refused` | The host did not accept the save. |
| `too_large` | The compressed state is larger than 1 GiB. |
| `archive_incomplete`, `archive_checksum`, `invalid_manifest` | The upload was incomplete or did not verify. Save again. |
| `expired` | The state is older than 30 days. |

The CLI exits with status 1 when the save fails, and prints the error code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.