Sessions and targets
Own one target, the emulator or Simulator your agent drives, and keep a journal of every verb it runs. A verb is one Autonom command, such as ui tap.
Try it autonom session start
Needs Autonom installed · a booted emulator or Simulator
How it works
Start with autonom devices. It lists Android emulators and iOS Simulators together, each with a running flag. Then session start binds one of them. While that session is current, every verb that names no target goes to it.
Sessions are machine-global. A second shell in any directory sees the same run, and a second session start is refused while one is live. To work on another device at the same time, start its session with --alongside; session list shows them all.
The journal records every verb, whether it worked, and your notes, with secrets masked. A reviewer reads what happened, not a summary of it. The screenshots and trees it names are the raw material of the evidence a run brings back, and each verb is one of the commands that read and drive the screen.
Examples
Every output here comes from Autonom’s test device, so you can rerun it without an emulator. Reproduce these outputs, at the end of this section, has the exact commands.
Pick a target when two are ready
Goal: bind the device you mean, not a guess.
- List the targets.
Android emulators and iOS Simulators come back in one list.
autonom devices - Start without naming one.
With two ready, Autonom refuses and names the candidates.
autonom session start
You should see two running emulators, a Simulator that is shut down, and a refusal.
What to look at. Both emulators are running, so session start exits 2 with ambiguous_target, an error code your agent can branch on. Pass one of the candidates to --target or --serial, as the next example does.
Show full output
Own a session and keep a note
Goal: bind one emulator, write down what you learned, and read it back.
- Start the session.
Name the target and the app under test.
autonom session start --serial emulator-5554 --app-id com.example.app - Write the finding down.
A note sits in the journal between the verbs around it.
autonom note add "login works; the 500 retry path is missing" - Read the notes back.
Filter the journal to notes only.
autonom journal --kind note
You should see the session’s folder, then your note with its place in the timeline.
What to look at. artifacts_dir is the folder that holds everything the session records. The note comes back as seq 2, right after session start.
Start over without losing the first run
Goal: stop the live session on purpose, because a second start never replaces it.
- Start a session.
This one is live until you stop it.
autonom session start --serial emulator-5554 --app-id com.example.app - Start again.
Autonom refuses and names the live session.
autonom session start --serial emulator-5554 --app-id com.example.app - Stop the first one.
Teardown reports each action, and the session’s files stay.
autonom session stop
You should see the refusal, then a stop that lists its teardown.
What to look at. The refusal, session_already_active, names the live session and its target. session stop reports every teardown action and never fails because one of them did.
Read a run back and hand it off
Goal: give a reviewer the whole timeline and the files to follow.
- Start the session.
The first entry in the journal.
autonom session start --serial emulator-5554 --app-id com.example.app - Read the screen.
The tree is saved with the run.
autonom ui tree --format outline --interactable - Note the finding.
Tag it with the task it belongs to.
autonom note add "login shows the generic error banner on 500; retry works" --task login - Read the timeline.
Every verb in order, whether it worked, and your notes.
autonom journal - List what can be followed.
Paths and hints for a second terminal.
autonom session outputs
You should see three entries in the order you ran them, and one stream to follow.
What to look at. The entries keep the order you ran them in, and the tree read names the file it saved under trees/. Paste shell_hint into a second terminal to follow the run live.
Show full output
Share a device between agents and a person
Goal: run two agents on two emulators, and keep everyone else off the device one of them is using.
- Start a named session.
The label is for people reading the list.
autonom session start --serial emulator-5554 --app-id com.example.app --label checkout - Start one on the second device beside it.
--alongsidekeeps the first session current.autonom session start --serial emulator-5556 --app-id com.example.app --alongside --label search - List the sessions.
It never touches a device.
autonom session list - Take the first device’s lease.
From now on only this holder may change it, for up to 600 seconds.
autonom control acquire --serial emulator-5554 --holder agent:checkout --ttl 600 - Try a tap without the claim.
Any other process, or this one without its claim, is refused.
autonom ui tap --serial emulator-5554 --desc "Sign in with Email" - Tap with the claim.
Pass the holder and the generation that acquire printed.
autonom --control-holder agent:checkout --control-generation 1 ui tap --serial emulator-5554 --desc "Sign in with Email" - Give the device back.
Then
control statusreadsfree.autonom control release --serial emulator-5554 --holder agent:checkout
You should see two labeled sessions, a lease at generation 1, a refused tap and an admitted one.
What to look at. control_held names the holder, and nothing reached the device. The admitted tap carries control, and the journal keeps its operation_id. A person’s first input in Mobile Canvas takes a free device the same way, and Take over there replaces an agent at once.
Show full output
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, so no device is needed. Ids and times differ on every run.
The shared-control example needs the control lease, which Autonom 0.36.0 adds (commit 4459bf1); run it from such a checkout, in a fresh shell.
Good to know
Name the target whenever more than one is ready. Pass
--target,--serialor--udid. Ambiguity is an error that lists the candidates, never a silent guess.A live session is never replaced.
session startrefuses until you runsession stop.journal --session-idstill reads a finished run.One command can name its session.
--session-idbinds a single command to that session without changing the current one. A stopped session stays readable and refuses anything else withsession_stopped; flags that name another target are refused withsession_target_mismatch.A Canvas workspace keeps its own sessions. Each device it attaches gets a session alongside yours, or reuses the live one on that target; yours stays current. A command with
--serialor--udidjoins the live session on that target, so its journal lands next to the Canvas's.The control lease decides who may change a device. With no lease, nothing changes. Once someone holds it, every command, flow step and Canvas input that changes the device needs the holder’s claim:
--control-holderand--control-generation, or theenvthatcontrol acquireprints. Reading the screen, screenshots, logs, the journal,session listandsession stopnever need it.An agent’s lease runs out. It lasts 60 seconds unless
--ttlsays otherwise, up to 3600. Renew it withcontrol renewbefore then, or the next action is refused withcontrol_lease_expired. A lease replaced by a person answerscontrol_generation_stale; never replay an input whose outcome you did not see.Only a person takes over.
control acquire --takeoveris refused for an agent holder. A person’s Take over in Mobile Canvas replaces any holder at once, andcontrol statusthen names the replaced holder intook_over_from.The lease is coordination, not security. It keeps cooperating processes of one user out of each other’s way. Any process of that user can take over with
--kind human, and admission is checked just before each device call, so one input already admitted can still land. Do not rely on it to keep a misbehaving agent off a device.session listskips what it cannot read. A broken session record is left out with asession_unreadablewarning.A failed install or launch never leaves a session current. The new session is stopped, and the error names it in its
session_rolled_backfield. The next command cannot drive a half-built session.The journal keeps secrets out. Typed text, secret-bearing flag values and every
KEY=VALUEoption value are masked. A journal error never fails your command.A flag that does nothing says so.
--log-stream,--argor--setenvon Android and--activityon iOS come back as aflag_ignored_on_platformwarning.Stop never kills what it did not start. An idb companion the session did not start is left alone, and a
companion_left_runningwarning names it.A session that died still gets found.
autonom doctorlists orphaned processes and any device left pointing at a dead proxy.autonom cleanupreaps the processes from any directory. The network proxy is one of them.
Reference
Every command also takes --platform, --target, --serial and --udid, before or after the verb.
| Command | What it does |
|---|---|
autonom devices [list] | Lists Android and iOS targets in one list, plus bootable emulator images and their hardware profiles. --platform narrows it to one platform. |
autonom devices boot | Starts an emulator by --avd and waits for boot, or boots a Simulator by --target. |
autonom devices shutdown [--target ID] | Shuts a target down. It refuses any serial that is not an emulator. |
autonom session start [--app-id ID] | Owns one target. --install and --launch install and open the app; a shut-down Simulator boots on its own. |
autonom session start --alongside --label TEXT | Starts one more session on another target, next to the current one; --label names any session for people. |
autonom session list [--all] | Lists the live sessions with their labels and which one is current; --all adds stopped ones. It never touches a device. |
autonom control status [--all] | The target’s lease: free or held, the holder, the generation and when it expires. |
autonom control acquire [--holder ID] [--kind agent|human] [--label TEXT] [--ttl SECONDS] [--takeover] | Takes the target’s lease and prints the claim to pass on. --takeover replaces a live holder, for a person only. |
autonom control renew [--holder ID] [--generation N] [--ttl SECONDS] | Extends your live lease at the same generation. |
autonom control release [--holder ID] [--generation N] | Gives the lease back; the generation is kept. |
--control-holder ID --control-generation N | The claim, before or after the verb; also AUTONOM_CONTROL_HOLDER and AUTONOM_CONTROL_GENERATION. --operation-id ID names the action in the journal. |
autonom session show|stop | Shows the current session, or stops it and tears down what it started. |
autonom session outputs | Lists every file you can follow, with a tail -f hint for a second terminal. |
autonom session launch <app-id> | Launches the app. --fresh starts it on a cleared task on Android, or after a terminate on iOS. |
autonom session force-stop|uninstall | Stops or removes the app you name. |
autonom session clear <app-id> | Clears the app’s data; --strategy picks how. The differences below say how it varies by platform. |
autonom note add <text> [--task T] | Writes a note into the journal, tagged with its task. |
autonom journal [--kind action|note] | Reads the timeline back. --follow streams it; --session-id reads a finished session. |
autonom processes | Lists what Autonom started, across the machine. |
autonom cleanup [--dry-run] [--all] | Reaps what Autonom started and left running, across the machine. |
Android and iOS differences
One session per investigation. On iOS the target is the Simulator; a Simulator on another Mac is reachable through its idb companion.
| Capability | Android | iOS Simulator |
|---|---|---|
| Clear app data | A full reset with pm clear | Uninstall and reinstall, which needs the app path from --install; the privacy strategy resets permissions only |
| Boot | devices boot waits until the emulator has booted | session start boots a shut-down Simulator itself |
| Shut down | Emulators only, never hardware | By UDID |
| Launch options | --activity; --fresh starts on a cleared task | --arg and --setenv; --fresh terminates the app first; --log-stream on session start |
Next steps
You own a session and can read every step back.