# Capabilities

Canonical URL: https://autonom.yatsuk.me/docs/capabilities/

Ask a target what works there before your agent relies on it. One command answers with a snapshot: each capability is available, degraded or unavailable, and anything short of available says why.

**Try it**

```sh
autonom capabilities
```

**Needs** [Autonom installed](https://autonom.yatsuk.me/docs/install/index.md) · [a ready emulator, Android phone or Simulator](https://autonom.yatsuk.me/docs/sessions/index.md)

## How it works

`autonom capabilities` describes a target, not a session. With a session it describes the session's target and fills in `session_id`. Without one it takes the target your flags name, or the only ready target, and `session_id` is `null`. That snapshot assumes nothing is attached yet, so `network.capture` is unavailable until a session attaches the capture proxy.

The answer is an `autonom.provider/v1` snapshot inside the usual `ok` envelope. `provider` is `local.android` or `local.ios`. `device_class` is `simulator` for an Android emulator or an iOS Simulator, and `physical` for an Android phone. `captured_at` says when it was taken. `capabilities` lists every capability by name, in alphabetical order.

| State | What it means |
| --- | --- |
| `available` | Works on this target now. |
| `degraded` | Works in a weaker form. `reason` says how, for example a checkpoint that restores by replaying the flow from its start. |
| `unavailable` | Does not work here. `reason` says why, for example a control that needs an emulator or Simulator. |
| `unknown` | Allowed by the schema for a provider that cannot tell. The local Android and iOS providers in v0.36.1 always answer with one of the other three. |

A snapshot is a record, not a promise: it never changes after `captured_at`. A flow can name the capabilities it needs under `requires`, and `flow run` takes a fresh snapshot and checks them before the first step. A missing one stops the run with [`flow_requirements_unmet`](https://autonom.yatsuk.me/docs/safety/index.md#flow_requirements_unmet) and nothing touches the device.

`--probe` adds a measurement. It reads the current screen once, so on iOS `ui.accessibility` and `ui.input` describe what was measured, not only which tools are installed. On Android the tree and input come from adb, so the answer is the same with or without it.

## Examples

Every output here comes from Autonom's test emulator, a test Android phone and a test Simulator, so you can rerun it without a device. Reproduce these outputs, at the end of this section, has the exact commands.

### See what an emulator can do

**Goal:** learn what your agent can rely on before it starts a long check.

1. **Ask the emulator.** No session is needed; `--serial` names the target.

   ```sh
   autonom capabilities --serial emulator-5554
   ```

You should see the snapshot, with each capability and its state.

*Output of autonom capabilities*

```
{
  "ok": true,
  "session_id": null,
  "schema": "autonom.provider/v1",
  "provider": "local.android",
  "target_id": "emulator-5554",
  "device_class": "simulator",
  "captured_at": "2026-10-19T06:45:26.128Z",
  "capabilities": [
    {
      "name": "checkpoint.create",
      "state": "degraded",
      "reason": "portable flow-prefix checkpoint"
    },
    …
    {
      "name": "network.capture",
      "state": "unavailable",
      "reason": "capture proxy is not attached"
    },
    …
  ]
}
```

**What to look at.** `device_class` is `simulator`, because an emulator can be reset and controlled from the host. `checkpoint.create` is degraded: a checkpoint restores by [replaying the flow](https://autonom.yatsuk.me/docs/replay/index.md) from its start. `network.capture` waits for a session to attach the [capture proxy](https://autonom.yatsuk.me/docs/network/index.md).

**Show full output**

```
{
  "ok": true,
  "session_id": null,
  "schema": "autonom.provider/v1",
  "provider": "local.android",
  "target_id": "emulator-5554",
  "device_class": "simulator",
  "captured_at": "2026-10-19T06:45:26.128Z",
  "capabilities": [
    {
      "name": "checkpoint.create",
      "state": "degraded",
      "reason": "portable flow-prefix checkpoint"
    },
    {
      "name": "checkpoint.restore",
      "state": "degraded",
      "reason": "replay from flow start"
    },
    {
      "name": "logs",
      "state": "available"
    },
    {
      "name": "network.capture",
      "state": "unavailable",
      "reason": "capture proxy is not attached"
    },
    {
      "name": "screen.stream",
      "state": "available"
    },
    {
      "name": "screenshots",
      "state": "available"
    },
    {
      "name": "simulator.appearance",
      "state": "available"
    },
    {
      "name": "simulator.battery",
      "state": "available"
    },
    {
      "name": "simulator.biometric",
      "state": "available"
    },
    {
      "name": "simulator.call",
      "state": "available"
    },
    {
      "name": "simulator.clipboard",
      "state": "available"
    },
    {
      "name": "simulator.keyboard",
      "state": "unavailable",
      "reason": "Android keeps keyboard preferences inside the keyboard app; no host-level store reaches them"
    },
    {
      "name": "simulator.location",
      "state": "available"
    },
    {
      "name": "simulator.network",
      "state": "available"
    },
    {
      "name": "simulator.permissions",
      "state": "available"
    },
    {
      "name": "simulator.push",
      "state": "unavailable",
      "reason": "the platform exposes no provider-neutral control"
    },
    {
      "name": "simulator.sms",
      "state": "available"
    },
    {
      "name": "simulator.status_bar",
      "state": "available"
    },
    {
      "name": "simulator.text_size",
      "state": "available"
    },
    {
      "name": "ui.accessibility",
      "state": "available"
    },
    {
      "name": "ui.input",
      "state": "available"
    }
  ]
}
```

### Compare it with an Android phone

**Goal:** see what changes when the target is a phone instead of an emulator.

1. **Ask the phone.** The serial is the one `adb devices` lists for it.

   ```sh
   autonom capabilities --serial R5CT20ABCDE
   ```

You should see `device_class` change, and the emulator-only controls become unavailable.

*Output of autonom capabilities for a phone*

```
{
  "ok": true,
  "session_id": null,
  "schema": "autonom.provider/v1",
  "provider": "local.android",
  "target_id": "R5CT20ABCDE",
  "device_class": "physical",
  …
  "capabilities": [
    {
      "name": "checkpoint.create",
      "state": "unavailable",
      "reason": "physical devices cannot be snapshotted"
    },
    {
      "name": "checkpoint.restore",
      "state": "unavailable",
      "reason": "physical devices require baseline replay"
    },
    …
    {
      "name": "simulator.location",
      "state": "unavailable",
      "reason": "requires an emulator or simulator"
    },
    …
    {
      "name": "ui.accessibility",
      "state": "available"
    },
    {
      "name": "ui.input",
      "state": "available"
    }
  ]
}
```

**What to look at.** The screen, input, screenshots and logs work the same. Every `simulator.*` control, such as a simulated location, needs an emulator. A phone cannot be snapshotted, so a replay always starts from the beginning of the flow.

### Measure the screen with --probe

**Goal:** tell an installed UI backend from one that can read this screen.

1. **Ask the Simulator without measuring.** The answer reflects the tools that are installed.

   ```sh
   autonom capabilities --udid AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB
   ```

2. **Ask again with `--probe`.** Autonom reads the current screen once before it answers.

   ```sh
   autonom capabilities --udid AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB --probe
   ```

You should see `ui.accessibility` available first, then degraded once the screen was read.

*Output of autonom capabilities without --probe*

```
{
  "ok": true,
  "session_id": null,
  "schema": "autonom.provider/v1",
  "provider": "local.ios",
  "target_id": "AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB",
  "device_class": "simulator",
  …
    {
      "name": "ui.accessibility",
      "state": "available"
    },
    …
}
```

*Output of autonom capabilities --probe*

```
{
  "ok": true,
  …
    {
      "name": "ui.accessibility",
      "state": "degraded",
      "reason": "empty_accessibility_tree"
    },
    {
      "name": "ui.input",
      "state": "available"
    }
  ]
}
```

**What to look at.** The idb backend is installed, so the first answer says available. The measured tree was empty, so `--probe` says degraded with the reason `empty_accessibility_tree`. On a real app that usually means its views carry no accessibility labels; [Read and drive the screen](https://autonom.yatsuk.me/docs/screen/index.md) explains what to do next.

### Name the target when several are ready

**Goal:** see what your agent gets when it asks without naming a target.

1. **Ask with no target flags.** An emulator, a phone and a Simulator are ready, so Autonom will not pick one.

   ```sh
   autonom capabilities
   ```

You should see one error object on stderr, with exit code 2.

*Output of autonom capabilities with three ready targets*

```
{"ok": false, "error_code": "ambiguous_target", "error": "3 ready targets; pass --target (or --platform)", "hint": "Candidates: android:emulator-5554, android:R5CT20ABCDE, ios:AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB", "candidates": [{"platform": "android", "target_id": "emulator-5554"}, {"platform": "android", "target_id": "R5CT20ABCDE"}, {"platform": "ios", "target_id": "AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB"}]}
```

**What to look at.** [`ambiguous_target`](https://autonom.yatsuk.me/docs/safety/index.md#ambiguous_target) lists the `candidates`. Pass one with `--target`, `--serial` or `--udid`, or narrow the list with `--platform`. Once a session owns a target, plain `autonom capabilities` describes that target.

### Let a flow refuse a target that lacks a capability

**Goal:** stop a flow before its first step when the target cannot do what the flow needs.

1. **Name the capability in the flow.** This flow checks requests, so it needs the capture proxy.

   *A flow that requires network capture*

   ```
   schema: autonom.dev/flow/v1
   appId: com.example.app
   name: Checkout requests
   requires:
     capabilities: [network.capture]
   ---
   - launchApp
   ```

2. **Run it in a session without the proxy.**

   ```sh
   autonom flow run checkout.yaml
   ```

You should see the run refused with exit code 2, before the app launches.

*Output of autonom flow run*

```
{"ok": false, "error_code": "flow_requirements_unmet", "error": "active provider does not satisfy required capabilities: network.capture", "hint": "Inspect the immutable capability snapshot and select a compatible target.", "missing_capabilities": ["network.capture"], "capability_details": [{"name": "network.capture", "state": "unavailable", "reason": "capture proxy is not attached"}]}
```

**What to look at.** `capability_details` carries the snapshot entry for each missing capability, reason included. Attach the proxy with `autonom network attach --i-understand-mitm`, or run the flow on a target that has what it needs.

### Reproduce these outputs

From the root of an Autonom checkout at tag v0.36.1 (commit ca2a280), in bash or zsh. The `autonom` function runs that checkout against its test doubles for adb, `simctl` and idb, so it needs no device, Xcode or idb. Session ids and times differ on every run.

*Script that reproduces the outputs*

```sh
# autonom below runs this checkout against Autonom's test emulator, an Android phone and a booted test Simulator.
S=$PWD W=/tmp/autonom-capabilities
rm -rf $W && mkdir -p $W
export AUTONOM_HOME=$W/.autonom AUTONOM_FAKE_STATE=$W/devices.json
autonom() { python3 $S/scripts/autonom.py --adb $S/tests/fakes/fake_adb.py --simctl $S/tests/fakes/fake_simctl.py --idb $S/tests/fakes/fake_idb.py "$@"; }
cat > $AUTONOM_FAKE_STATE <<JSON
{"devices": [["emulator-5554", "device", "product:sdk_gphone64_arm64"], ["R5CT20ABCDE", "device", "product:a54x"]],
 "simctl_devices": {"devices": {"com.apple.CoreSimulator.SimRuntime.iOS-26-0": [{"udid": "AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB", "name": "iPhone 17 Pro", "state": "Booted", "isAvailable": true}]}}}
JSON
# See what an emulator can do
autonom capabilities --serial emulator-5554
# Compare it with an Android phone
autonom capabilities --serial R5CT20ABCDE
# Measure the screen with --probe
autonom capabilities --udid AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB
autonom capabilities --udid AAAAAAAA-1111-2222-3333-BBBBBBBBBBBB --probe
# Name the target when several are ready
autonom capabilities
# Let a flow refuse a target that lacks a capability
printf '%s\n' 'schema: autonom.dev/flow/v1' 'appId: com.example.app' 'name: Checkout requests' 'requires:' '  capabilities: [network.capture]' '---' '- launchApp' > $W/checkout.yaml
autonom session start --serial emulator-5554 --app-id com.example.app > /dev/null
autonom flow run $W/checkout.yaml
autonom session stop > /dev/null
```

## Good to know

- **Ask before a long check, not after it fails.** A snapshot costs one command. It tells your agent early that a phone has no simulated location, or that the proxy is not attached yet.
- **A snapshot never changes.** Take a new one after you attach the proxy, start a session or switch targets; `captured_at` says which one you are reading.
- **Use `--probe` on iOS when the screen matters.** Without it, `ui.accessibility` says whether idb is ready. With it, the answer is what Autonom measured on the current screen. While a session runs, a screen read from the last minute refines the plain snapshot too.
- **An unknown capability name is refused early.** `flow check` rejects a name under `requires.capabilities` that Autonom does not know, with the list of valid names, so a typo never reaches the device.
- **Setup implies capabilities.** A flow whose `setup` sets a location, permissions, orientation, appearance or network also requires the matching capability, without listing it under `requires`.
- **Every run keeps its snapshot.** A flow run records the snapshot it was checked against, and the [agent report](https://autonom.yatsuk.me/docs/agent-report/index.md) repeats it under `capabilities`.

## Reference

The command and the flags that pick its target.

| Command | What it does |
| --- | --- |
| `autonom capabilities` | Prints the snapshot of the session's target, or of the only ready target when no session runs. |
| `autonom capabilities --probe` | Reads the current screen once first, so the UI entries describe what was measured. |
| `--serial SERIAL` | Picks an Android emulator or phone by its adb serial. |
| `--udid UDID` | Picks an iOS Simulator by its UDID. |
| `--target TARGET` | Picks a target by id, such as one of the `candidates` of `ambiguous_target`. |
| `--platform android\|ios` | Limits the choice to one platform. |
| `--session-id ID` | Binds the command to one session when several run. |

The capabilities a snapshot lists.

| Capability | What it covers |
| --- | --- |
| `ui.accessibility` | Reading the screen as a UI tree. |
| `ui.input` | Taps, swipes, keys and typed text. |
| `screenshots`, `screen.stream` | Screenshots, and the live view in the Mobile Canvas. |
| `logs` | Device logs. |
| `network.capture` | Requests through the capture proxy. Available once a session has attached it. |
| `checkpoint.create`, `checkpoint.restore` | Saving and restoring a point in a flow. Degraded on an emulator or Simulator, where restoring replays the flow from its start; unavailable on a phone. |
| `simulator.location`, `simulator.permissions` | Simulated location and permission changes. |
| `simulator.appearance`, `simulator.text_size`, `simulator.status_bar`, `simulator.battery`, `simulator.clipboard`, `simulator.biometric`, `simulator.keyboard` | The `simulator` controls both platforms share, where the platform allows them. |
| `simulator.network`, `simulator.sms`, `simulator.call` | Network shaping, text messages and calls: Android emulator only. |
| `simulator.push` | Push notifications: iOS Simulator only. |

## Android and iOS differences

Both providers answer with the same snapshot; the values differ with the platform and the kind of device.

| Capability | Android | iOS Simulator |
| --- | --- | --- |
| Device class | `simulator` on an emulator, `physical` on a phone | `simulator` |
| UI tree and input | From adb; `--probe` changes nothing | From idb or XCUITest; `--probe` measures the screen |
| Checkpoints | Partly: degraded on an emulator, unavailable on a phone | Partly: degraded |
| Network, SMS and calls | Yes, on an emulator | No |
| Push | No | Yes |
| Keyboard preferences | No | Partly: applied at boot |

## Next steps

You can see what a target supports before your agent relies on it.

- [Replay](https://autonom.yatsuk.me/docs/replay/index.md): Rebuild the state of a recorded run, step by step.
- [Sessions and targets](https://autonom.yatsuk.me/docs/sessions/index.md): Own one target, so every command lands on it.
- [Flows](https://autonom.yatsuk.me/docs/flows/index.md): Name what a flow requires in its header.
- [Safety and errors](https://autonom.yatsuk.me/docs/safety/index.md): Branch on every error code the docs show.