Environment Variables¶
Most users can use the defaults. Set these variables when you need a different state directory, logs, tool set, or device behavior.
Each name below with an AUTO_MOBILE_ spelling is a legacy alias. When a cell
lists two names, the first takes precedence when set. Defaults are the behavior
with the variable unset. Accepted values:
- A flag whose row says
1/trueaccepts1,true,yesoron, trimmed and case-insensitive; any other value is off. - A row that says exact accepts only the values it shows.
- Unknown numeric values usually fall back to the default unless the row says otherwise.
State and logs¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_DATA_DIR, AUTO_MOBILE_DATA_DIR |
Base directory for observations, navigation data, CtrlProxy builds, streaming, tool outputs and downloaded tools; filesystem path, relative to the daemon launch directory. | ~/.auto-mobile (OS temp fallback if home is unavailable) |
AUTOMOBILE_LOG_DIR, AUTO_MOBILE_LOG_DIR |
Daemon and client log directory; filesystem path. | $AUTOMOBILE_DATA_DIR/logs |
AUTOMOBILE_PLAN_HEALTH_DIR |
Each executePlan run writes a JSON health summary (per-tool step latency, failures, skips) here and attaches it as healthSummary in the result; filesystem path. |
unset (no summary) |
AUTOMOBILE_CAPTURE_FIXTURES_DIR |
Fixture capture mode: each tool call writes the host commands it ran (argv, output, exit code, duration) and the device it used into its own directory here; filesystem path. Commands that type into a password field are recorded without their arguments. | unset (no capture) |
AUTOMOBILE_LOG_FORMAT, AUTO_MOBILE_LOG_FORMAT |
Log format: text or newline-delimited json. |
text |
AUTOMOBILE_LOG_SINK, AUTO_MOBILE_LOG_SINK |
Log destination: file, stderr, both. |
file |
AUTOMOBILE_LOG_LEVEL, AUTO_MOBILE_LOG_LEVEL |
Logging threshold: debug, info, warn/warning, error, none/silent. |
info |
AUTOMOBILE_COORDINATION_DIR, AUTO_MOBILE_COORDINATION_DIR |
Shared directory for coordination between AutoMobile agents, including the iOS CtrlProxy bundle cache and signing entitlements; absolute path shared by cooperating agents. Set it when the home directory is read-only. | OS account home .auto-mobile |
AUTOMOBILE_ADB_SERVER_COORDINATION_DIR, AUTO_MOBILE_ADB_SERVER_COORDINATION_DIR |
Directory where daemons sharing one ADB server record device claims and emulator boots; absolute path, the same for every daemon on that server. | OS account home .auto-mobile/adb-servers |
AUTOMOBILE_TOOL_OUTPUTS_DIR, AUTO_MOBILE_TOOL_OUTPUTS_DIR |
Directory for large CLI tool-output files; filesystem path. CLI --tool-outputs-dir wins. |
data directory tool_outputs |
AUTOMOBILE_DEBUG |
CLI debug logging; 1/true enables. A failed IME-backed sendKeys type command can then return a captured input-method commit trace as imeTrace; a successful one logs a captured trace at debug level. |
off |
AUTOMOBILE_DEBUG_PERF |
UI performance debug tracking; 1/true enables (also --debug-perf/--ui-perf-debug). |
off |
AUTOMOBILE_DOCTOR_TIMEOUT_MS |
doctor command timeout; positive integer milliseconds. Anything else is ignored with a warning. |
5000 ms |
For container log collection:
export AUTOMOBILE_DATA_DIR=/var/lib/automobile
export AUTOMOBILE_LOG_FORMAT=json
export AUTOMOBILE_LOG_SINK=stderr
# The container's only daemon uses this data dir; see "Shared-namespace guard" below.
export AUTOMOBILE_ALLOW_SHARED_DAEMON_NAMESPACE=1
AUTOMOBILE_DATA_DIR does not move the SQLite database (AUTOMOBILE_DB_DIR /
AUTOMOBILE_DB_PATH), auxiliary daemon sockets (AUTOMOBILE_AUX_SOCKET_DIR), or
coordination directories. Set AUTOMOBILE_COORDINATION_DIR to move coordination
state. The iOS bundle cache can also be moved with
AUTOMOBILE_CTRL_PROXY_IOS_CACHE_DIR.
Daemon namespace¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_DAEMON_SOCKET_PATH, AUTO_MOBILE_DAEMON_SOCKET_PATH |
Daemon control socket; filesystem path. | /tmp/auto-mobile-daemon-<uid>.sock |
AUTOMOBILE_DAEMON_PID_FILE_PATH, AUTO_MOBILE_DAEMON_PID_FILE_PATH |
Daemon PID record; filesystem path. | /tmp/auto-mobile-daemon-<uid>.pid |
AUTOMOBILE_DAEMON_LOCK_FILE_PATH, AUTO_MOBILE_DAEMON_LOCK_FILE_PATH |
Daemon start lock; filesystem path. | /tmp/auto-mobile-daemon-<uid>.lock |
AUTOMOBILE_DAEMON_TOKEN_FILE_PATH |
Daemon HTTP token file (mode 0600) that clients read to authenticate; filesystem path. | /tmp/auto-mobile-daemon-<uid>.token |
AUTOMOBILE_DAEMON_HTTP_TOKEN |
Client-side: the daemon HTTP bearer token to send instead of reading the token file. | unset |
AUTOMOBILE_MCP_MODERN_ERA |
Enable MCP 2026-07-28 envelope requests on the daemon HTTP endpoint; 1/true/yes/on enables. |
off |
AUTOMOBILE_ELICITATION |
off never asks your MCP client which device to use when a call matches several; the call returns the ambiguous_device_target refusal instead. Use it in CI and benchmarks. |
on |
AUTOMOBILE_AUX_SOCKET_DIR |
Directory for auxiliary stream sockets; filesystem path. When set, the control socket, PID and lock files also move to a per-directory name, so a second daemon never touches the default daemon’s files (an explicit AUTOMOBILE_DAEMON_*_PATH still wins). |
~/.auto-mobile |
AUTOMOBILE_WEBRTC_STREAM_SOCKET_PATH, AUTO_MOBILE_WEBRTC_STREAM_SOCKET_PATH |
WebRTC stream socket; filesystem path. | auxiliary socket directory webrtc-stream.sock |
AUTOMOBILE_DAEMON_TIMEOUT_MS, AUTO_MOBILE_DAEMON_TIMEOUT_MS |
Connection and request timeout; positive integer milliseconds. | 120000 ms |
AUTOMOBILE_DAEMON_STARTUP_TIMEOUT_MS, AUTO_MOBILE_DAEMON_STARTUP_TIMEOUT_MS |
Cold startup budget; positive integer milliseconds, capped at 2147483647. |
30000 ms |
AUTOMOBILE_DAEMON_EXISTING_REACHABILITY_TIMEOUT_MS, AUTO_MOBILE_DAEMON_EXISTING_REACHABILITY_TIMEOUT_MS |
How long to wait for an already-running daemon to answer; positive integer milliseconds, capped at two-thirds of the startup budget. | 10000 ms, subject to cap |
AUTOMOBILE_DAEMON_DISABLE_HANDSHAKE, AUTO_MOBILE_DAEMON_DISABLE_HANDSHAKE |
Disable the version and build handshake with the daemon; 1/true disables. |
off; handshake enabled |
AUTOMOBILE_DAEMON_STREAM_AUTH |
Require session authentication on video and WebRTC sockets; 0, false, no, off disable. |
on |
AUTOMOBILE_OPEN_LINK_MCP_TIMEOUT_MS, AUTO_MOBILE_OPEN_LINK_MCP_TIMEOUT_MS |
openLink time budget; positive integer milliseconds. Set it in the daemon environment (the daemon wins if both client and daemon set it). |
90000 ms |
AUTOMOBILE_OBSERVE_MCP_TIMEOUT_MS, AUTO_MOBILE_OBSERVE_MCP_TIMEOUT_MS |
observe time budget; same rules as openLink. |
90000 ms |
AUTOMOBILE_RUNNER_READINESS_TIMEOUT_MS, AUTO_MOBILE_RUNNER_READINESS_TIMEOUT_MS |
CtrlProxy readiness timeout; integer milliseconds in 1000..120000. CLI flag wins. |
30000 ms |
AUTOMOBILE_CTRL_PROXY_LEASE_IDLE_MS |
Idle time after which the daemon closes a device’s CtrlProxy connection and releases its port forwarding; positive integer milliseconds. | 60000 ms |
AUTOMOBILE_ALLOW_SHARED_DAEMON_NAMESPACE |
Let daemon lifecycle commands and automatic client restarts act on the default daemon while a state directory is relocated (see “Shared-namespace guard”); exact 1 enables. |
unset |
Set AUTOMOBILE_DAEMON_SOCKET_PATH, AUTOMOBILE_DAEMON_PID_FILE_PATH, and
AUTOMOBILE_DAEMON_LOCK_FILE_PATH to distinct absolute paths for each concurrent
instance. Relative paths resolve from the daemon launch directory.
Shared-namespace guard¶
AUTOMOBILE_DATA_DIR, AUTOMOBILE_DB_DIR and AUTOMOBILE_DB_PATH relocate a
daemon’s state, but not its socket. Suppose any of them is set, and neither
AUTOMOBILE_AUX_SOCKET_DIR nor a non-default AUTOMOBILE_DAEMON_SOCKET_PATH is.
Then --daemon start, stop, restart, release-session and set-feature-flag
refuse with [shared_daemon_namespace]: they would act on the default daemon,
which runs on different state. MCP and --cli clients likewise refuse an automatic
restart, though they still start a daemon when none is running.
AUTOMOBILE_LOG_DIR and the coordination directories do not count.
Set AUTOMOBILE_AUX_SOCKET_DIR to use a separate daemon instead. To act on the
default daemon deliberately, pass --allow-shared-namespace after the daemon
command, or set AUTOMOBILE_ALLOW_SHARED_DAEMON_NAMESPACE=1 on hosts whose only
daemon uses the relocated state, such as a container.
A daemon that exits on its own is replaced with the same port and startup flags.
The replacement runs with the new client’s environment, so environment-only
settings follow the new client. Run --daemon stop first for a fresh set of
flags.
Database¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_DB_PATH, AUTO_MOBILE_DB_PATH |
Exact SQLite database file; filesystem path. Takes precedence over the DB directory. | ~/.auto-mobile/auto-mobile.db |
AUTOMOBILE_DB_DIR, AUTO_MOBILE_DB_DIR |
Directory containing auto-mobile.db; filesystem path. |
~/.auto-mobile |
AUTOMOBILE_MIGRATIONS_DIR, AUTO_MOBILE_MIGRATIONS_DIR |
Directory of migration modules; filesystem path. | bundled migrations |
AUTOMOBILE_MIGRATION_RECOVERY, AUTO_MOBILE_MIGRATION_RECOVERY |
Safe migration-history recovery is on unless 0, false, no, off. Only exact 1 also permits a destructive table reset. |
safe recovery on; destructive reset off |
AUTOMOBILE_MIGRATION_LOCK_TIMEOUT_MS, AUTO_MOBILE_MIGRATION_LOCK_TIMEOUT_MS |
How long to wait for the migration lock; positive integer milliseconds. | 60000 ms |
Relative paths resolve from the daemon’s launch directory. Use a path unique to each concurrent instance:
export AUTOMOBILE_DB_PATH="$PWD/.auto-mobile/auto-mobile.db"
Tool defaults¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_ENABLED_TOOLS |
Comma-separated tool names to enable; exact, case-sensitive. Unknown names and enable/disable conflicts fail startup. | unset |
AUTOMOBILE_DISABLED_TOOLS |
Comma-separated tool names to disable; same rules. | unset |
AUTOMOBILE_ALWAYS_LOAD_TOOLS |
Register optional tool definitions up front; 1/true enables. |
off |
AUTOMOBILE_PROTOTYPE_FULL_SCHEMA |
Inline the full prototype spec JSON Schema in the prototype tool’s spec field instead of pointing to the automobile:prototype/spec-schema resource; 1/true enables. Set on the MCP client, it applies to that client’s connection even when the shared daemon was started without it; set on the daemon, every connection gets the full schema. |
off |
AUTOMOBILE_OBSERVE_RESULT_INCLUDE_ELEMENTS |
Include a flattened elements list in observations; exact 1 enables, or the matching CLI flag. |
off |
AUTOMOBILE_TOOL_RESULTS_NO_STRUCTURED_CONTENT |
Omit structured tool content; exact 1 enables, or the matching CLI flag. |
off |
AUTOMOBILE_SERVER_INSTRUCTIONS |
Return a short usage instructions block when your MCP client connects; 1/true enables. |
off |
AUTOMOBILE_ACTIONS_DIFF_OBSERVE |
Return differential observations after actions; exact 1 enables, or the matching CLI flag. |
off |
AUTOMOBILE_ACTIONS_NO_OBSERVE |
Skip the observation after actions; exact 1 enables, or the matching CLI flag. |
off |
AUTOMOBILE_ACTIONS_COMPACT_METADATA |
Omit unchanged metadata and duplicate matches from action results; exact 0 opts out, 1 opts in. CLI flags win. |
on |
AUTOMOBILE_EVENT_ALL_MARKERS |
Comma-separated event markers that switch capture to all events; --event-all-markers wins. |
empty list |
export AUTOMOBILE_ENABLED_TOOLS=clipboard,sqlQuery
export AUTOMOBILE_DISABLED_TOOLS=observe
Repeatable --enable-tool and --disable-tool flags override these values, and
setToolEnabled choices override startup defaults.
Experimental session broker¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_SESSION_BROKER_CONFIG |
Path to a JSON configuration file, relative to the daemon launch directory. Enables the experimental session-only broker and supplies its capacity limits and device defaults. | unset; ordinary daemon mode |
AUTOMOBILE_SESSION_CONFIG |
A session request as inline JSON or a JSON file path. --session-config takes precedence. Cannot be combined with --initial-session-uuid or --no-proxy. |
unset; ordinary proxy mode |
See the session broker experiment for the file formats.
Session heartbeat timeout¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_SESSION_HEARTBEAT_TIMEOUT_MS, AUTO_MOBILE_SESSION_HEARTBEAT_TIMEOUT_MS |
How long a session owner may go without a heartbeat before the session is at risk of release; positive integer milliseconds. | 4000 ms |
AUTOMOBILE_SESSION_HEARTBEAT_CHECK_INTERVAL_MS, AUTO_MOBILE_SESSION_HEARTBEAT_CHECK_INTERVAL_MS |
How often the daemon checks for expired heartbeats; positive integer milliseconds. | 2000 ms |
AUTOMOBILE_SESSION_IDLE_TIMEOUT_MS, AUTO_MOBILE_SESSION_IDLE_TIMEOUT_MS |
Idle window after a session’s last control call; positive integer milliseconds. Set it in both the daemon and proxy environments. | 120000 ms |
AUTOMOBILE_SESSION_HEARTBEAT_INITIAL_GRACE_MS, AUTO_MOBILE_SESSION_HEARTBEAT_INITIAL_GRACE_MS |
Grace period before the first heartbeat of a custom-heartbeat session; positive integer milliseconds. | 20000 ms |
AUTOMOBILE_SESSION_PRE_FIRST_HEARTBEAT_GRACE_MS, AUTO_MOBILE_SESSION_PRE_FIRST_HEARTBEAT_GRACE_MS |
Grace period for default sessions that never send a heartbeat; positive integer milliseconds. | 5000 ms |
export AUTOMOBILE_SESSION_HEARTBEAT_TIMEOUT_MS=20000
At the default settings, AutoMobile releases a device session about 10 s after its owner’s last heartbeat. The MCP proxy heartbeats automatically, so a late or lost beat does not lapse the session.
Only control calls extend a session’s idle window (2 minutes by default), even
while its proxy stays connected. Raise AUTOMOBILE_SESSION_IDLE_TIMEOUT_MS if
your workflow only observes for long stretches; see
device ownership.
Idle time includes host sleep, so a laptop that sleeps longer than the window may
lose its session. The next call then fails with bound_session_lost; acquire a
new session with getAndroid or getApple.
If the proxy cannot get heartbeats acknowledged after three recovery attempts, it returns a structured error on the next call that uses the session:
daemon_stalled: the daemon stopped answering. Restart the daemon, then resume by passing the samesessionUuidon a tool call.proxy_stalled: the proxy itself stalled and the daemon released the session. Reacquire the device withgetAndroidorgetApple.
To restart a proxy and keep its sessions, start it with --initial-session-uuid
and a stable --liveness-owner-token <token>. Use a distinct token per harness.
A one-shot --cli call needs no keeper, and --daemon heartbeat on a CLI session
is a no-op.
--daemon session-info <session-id> prints a session’s binding.
--daemon active-sessions includes the same fields for every held session.
| Field | Meaning |
|---|---|
| device, platform | The bound device and its platform |
lastToolActivityAt |
The session’s last tool call |
idleReleaseAt |
When the idle window releases the session |
liveness |
The lease’s liveness |
stableDeviceId |
The device’s stable identity, when known |
deviceGeneration |
Serial changes so far; zero initially |
previousDeviceId |
The serial before the last change, after one |
AutoMobile can recover a retained session onto a new serial. Its proxy then sends
an MCP logging notification at level info, logger auto-mobile.liveness, with
this data:
{ code: "session_device_rebound", sessionUuid, previousDeviceId, deviceId,
stableDeviceId?, avdName?, generation }
avdName is the Android AVD name when known. Moving the session yourself with
setActiveDevice or an explicit bind sends no notification. A client logging
threshold above info suppresses it.
After the first serial change, admitted daemon tool results also carry:
_meta["automobile/sessionDevice"] = { sessionUuid, deviceId, stableDeviceId?,
generation, previousDeviceId }
Compare sessionUuid and stableDeviceId across results to verify the same
session and device image, with the new deviceId and an incremented generation.
See device-loss retry guidance.
CLI session lifetime¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_CLI_SESSION_IDLE_TIMEOUT_MS, AUTO_MOBILE_CLI_SESSION_IDLE_TIMEOUT_MS |
Idle timeout for sessions held from --cli; integer milliseconds of at least 120000 (smaller or non-numeric values are ignored with a warning), capped at one hour. |
120000 ms |
Each --cli call is its own process and cannot send heartbeats. AutoMobile
releases a session used from --cli this long after its last --cli tool call:
export AUTOMOBILE_CLI_SESSION_IDLE_TIMEOUT_MS=600000
Each invocation reads the value, so a change applies on the next call with no daemon restart.
Automatic observation screenshots¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_ACTION_OBSERVATION_SKIP_SCREENSHOT |
Skip the automatic screenshot after actions; false or 0 takes a final screenshot. |
skip |
AUTOMOBILE_OBSERVE_WAIT_FOR_SKIP_SCREENSHOT |
Skip the final observe.waitFor screenshot; false or 0 enables it. Intermediate polls still skip. |
skip |
AUTOMOBILE_OBSERVE_SETTLED_SCREENSHOT |
Screenshot mode: true/1 waits for a fresh screenshot that matches the observation (settled); any other set value selects async. A per-call mode wins. |
unset; async |
AUTOMOBILE_MAX_OBSERVATION_AGE_MS |
How old a cached view hierarchy may be before it is refreshed; positive integer milliseconds. | 5000 ms |
Explicit observe calls keep their own screenshot behavior. Observations taken
automatically after an action, or while resolving observe.waitFor, skip
screenshots by default. To get one screenshot from the final result:
export AUTOMOBILE_ACTION_OBSERVATION_SKIP_SCREENSHOT=false
export AUTOMOBILE_OBSERVE_WAIT_FOR_SKIP_SCREENSHOT=false
An action observation with a screenshot reports screenshotHierarchyLagMs, the
milliseconds between its hierarchy and its screenshot. If the screenshot is more
than 500 ms later, the observation also has screenshotHierarchyMismatch: true
and a freshness.warning. The image may then show a later screen than the
hierarchy: trust the hierarchy, and call observe for a matching screenshot.
Android captures try CtrlProxy before ADB and wait at most three seconds for CtrlProxy. After a recent failure, captures go straight to ADB for 60 seconds before trying CtrlProxy again. Prototype-hidden captures fail if CtrlProxy cannot capture them; they never switch to ADB. When capture diagnostics are available, the observation reports:
| Field | Meaning |
|---|---|
screenshotFallback |
ADB captured the image. |
screenshotFallbackReason |
Why: ctrlproxy_timeout for a timeout, ctrlproxy_recent_failure for the cooldown. |
screenshotStageDurationsMs |
totalMs plus ctrlProxyMs and/or adbMs for the stages attempted, including encoding and saving the image. |
screenshotCaptureSource |
On observe, device or observation-cache; on screenshot stream frames, the capture backend. |
Settled mode costs roughly 170 ms per Android observation and 20-70 ms per iOS
observation over async. When only one call needs a matching screenshot, pass
observe({ screenshot: "settled" }) instead of setting the variable.
Screenshot retention¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_SCREENSHOT_CACHE_MB |
Base screenshot cache capacity; positive MiB. | 128 MiB |
AUTOMOBILE_SCREENSHOT_CACHE_PER_DEVICE_MB |
Capacity per active device; positive MiB. | 64 MiB |
AUTOMOBILE_SCREENSHOT_CACHE_CEILING_MB |
Host cache ceiling; positive MiB, never lowers the base. Frames inside their 10-minute guarantee grow the cache up to it. | 2048 MiB |
AUTOMOBILE_SCREENSHOT_KEEP_PER_DEVICE |
Newest screenshots per device evicted only as a last resort; nonnegative integer, 0 disables fairness. |
3 |
How the cache sizes and evicts:
- Capacity is the larger of the base and active devices × per-device capacity, limited by the ceiling (or the base if larger).
- A device is active while any of its screenshots has an unexpired retention guarantee; an incoming capture also counts.
- Files without a device identity do not increase capacity.
- Eviction removes each device’s newest screenshots last.
- AutoMobile still admits a capture when nothing fits.
Device behavior¶
Android rebind commands and iOS keep-booted reset steps have budgets that scale with host load:
- When the one-minute host load per CPU core exceeds 1, the budget scales by it, up to the configured maximum. Unknown load uses the base budget.
- Setting MAX equal to the base disables scaling.
- A budget timeout allows one retry with up to twice the first budget, bounded by MAX. iOS waits for the abandoned step to settle before retrying.
- AutoMobile reports exhausted budgets as budget-driven fallback reasons.
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_CONTENT_SEEDER_APK_PATH |
Debug content seeder APK for contacts, calendar and SMS fixtures. | built debug APK in the checkout |
AUTOMOBILE_CTRL_PROXY_REBIND_WRITE_TIMEOUT_MS |
Base timeout for each Android accessibility rebind command. Positive integer milliseconds. | 5000 ms |
AUTOMOBILE_CTRL_PROXY_REBIND_WRITE_TIMEOUT_MAX_MS |
Ceiling for Android accessibility rebind command timeouts. Positive integer milliseconds. | 30000 ms |
AUTOMOBILE_IOS_RESET_STEP_BUDGET_MS |
Base budget for each iOS keep-booted reset step and health probe. Positive integer milliseconds. | 30000 ms |
AUTOMOBILE_IOS_RESET_STEP_BUDGET_MAX_MS |
Ceiling for iOS keep-booted reset step and health probe budgets. Positive integer milliseconds. | 120000 ms |
AUTOMOBILE_IOS_WARMUP_DEVICES |
Comma-separated simulator UDIDs that get startup warm-up and observation streams without a session. | empty list |
AUTOMOBILE_ANDROID_APPEARANCE_SYNC_DEVICES |
Comma-separated Android serials that get appearance sync without a session. | empty list |
AUTOMOBILE_ANDROID_OBSERVATION_STREAM_DEVICES |
Comma-separated Android serials that get observation streams without a session. | empty list |
AUTOMOBILE_APPEARANCE_SYNC |
Sync the host’s light/dark appearance to devices; 0, false, off, no disable. |
on |
AUTOMOBILE_ALLOW_DEVICE_CREATE |
Permit emulator and simulator creation; 1/true enables. An explicit --create-if-missing flag wins. |
off |
AUTOMOBILE_DEVICE_RECOVERY_ON_LOSS, AUTO_MOBILE_DEVICE_RECOVERY_ON_LOSS |
Exact 0 disables session continuity; exact 1 also lets eligible Android emulators be restarted. Other values warn and disable restart. |
continuity on; restart off |
AUTOMOBILE_ANDROID_REBOOT_ON_DEATH, AUTO_MOBILE_ANDROID_REBOOT_ON_DEATH |
Deprecated fallback for AUTOMOBILE_DEVICE_RECOVERY_ON_LOSS; same values. |
unset |
AUTOMOBILE_DEVICE_RECOVERY_MAX_ATTEMPTS, AUTO_MOBILE_DEVICE_RECOVERY_MAX_ATTEMPTS |
Emulator restarts allowed per window; integer 1..10. |
2 |
AUTOMOBILE_DEVICE_RECOVERY_WINDOW_MS, AUTO_MOBILE_DEVICE_RECOVERY_WINDOW_MS |
Window for the restart budget; positive integer milliseconds. | 900000 ms |
AUTOMOBILE_DEVICE_POOL_MATCHING, AUTO_MOBILE_DEVICE_POOL_MATCHING |
Which matching device to pick: exact LATEST, RANDOM, MINIMUM. |
LATEST |
AUTOMOBILE_DEVICE_POOL_AUTOLOCK, AUTO_MOBILE_DEVICE_POOL_AUTOLOCK |
Require a session UUID for an acquired device and release it when idle; exact 1 enables. |
off |
AUTOMOBILE_DEVICE_POOL_TIMEOUT, AUTO_MOBILE_DEVICE_POOL_TIMEOUT |
Autolock idle timeout in seconds; positive integer. | 60 seconds |
AUTOMOBILE_EMULATOR_HEADLESS |
Exact true forces headless, false forces a window; other values detect. |
headless on macOS and Linux without a display; otherwise windowed |
AUTOMOBILE_EMULATOR_AUDIO |
Exact false launches with -no-audio, which disables emulator audio, so audio tests cannot pass. See Headless host audio setup. |
audio on |
AUTOMOBILE_EMULATOR_NETSIM_ISOLATION |
Exact true gives each newly launched Android emulator a private netsimd, keeping its BLE peripherals invisible to other sessions; an explicit -packet-streamer-endpoint takes precedence. |
off |
AUTOMOBILE_EMULATOR_ARGS |
Extra emulator arguments as a JSON array of nonempty strings; malformed values fail. | empty array |
AUTOMOBILE_EMULATOR_EXCLUDED_CONSOLE_PORTS |
Even emulator console ports (5554-5682) or emulator-<port> serials AutoMobile must not use, comma- or whitespace-separated. A blank value allows all. |
5554 when a session broker config is set; otherwise empty |
AUTOMOBILE_LMK_PRESSURE_DIR |
Directory containing per-ABI Android memory-pressure binaries. When set, the release binary is never downloaded. | build/lmk-pressure under the package root, then the release download |
AUTOMOBILE_BUNDLETOOL_JAR |
bundletool-all jar, run with java, for installApp of .aab/.apks; otherwise bundletool on PATH. Never downloaded. |
unset |
AUTOMOBILE_HEADLESS |
1/true runs the prototype tool on an in-memory virtual device with no real device, as --headless does. See Headless prototypes. |
unset |
AUTOMOBILE_IOS_HEADLESS |
On macOS, exact true/1 runs headless and any other set value shows a window. Non-macOS is always headless. |
detect a graphical login session |
AUTOMOBILE_BOOT_CAPACITY_GATE |
Boot limit check for emulator and simulator cold boots; exact 0 disables it on both platforms. See Boot capacity. |
on |
AUTOMOBILE_IOS_TEMPLATE_CLONE |
Clone new iOS simulators from settled templates; off by default until clone isolation is device-verified, 1/true opts in. No template yet: normal create. |
false |
AUTOMOBILE_IOS_PREBOOT_LEAN_PROFILE |
New iOS simulators: none, minimal, or catalog-cpu; none opts out; unknown values use minimal. Explicit resources override the profile. |
minimal |
AUTOMOBILE_IOS_SUPPRESS_APSD_LOG |
New iOS sims: turn off only the com.apple.apsd log subsystem before first boot; apsd’s other logs remain. Exact 1/true (trimmed, any case) opts in; persists. Hides push debug logs; push unaffected. |
false |
AUTOMOBILE_IOS_SIM_CAPACITY_GATE |
iOS-only override of the gate above: exact 0 disables, exact 1 enables. |
unset (follows the shared switch) |
AUTOMOBILE_ANDROID_MAX_BOOTED |
Cap on concurrently booted Android emulators; positive integer. Invalid values are ignored with a warning. | derived from host RAM and cores, at least 1 |
AUTOMOBILE_ANDROID_BOOT_BUDGET_VCPUS |
configured sizes the Android boot limit with the vCPU count the AVD about to boot resolved to (hardware-qemu.ini, 4 on AVDs AutoMobile creates) instead of two cores per emulator. Any other value keeps two. |
fixed (two cores per emulator) |
AUTOMOBILE_IOS_SIM_BOOT_CONCURRENCY |
Concurrent iOS simulator boot bursts; positive integer. Extra boots queue in FIFO order. Invalid values warn and use the derived limit. | ceil(host cores / 13), at least 2 |
AUTOMOBILE_IOS_SIM_MAX_BOOTED |
Cap on concurrently booted iOS simulators; positive integer. Invalid values are ignored with a warning. | derived from 60% of host RAM over measured footprint and CPU cost |
AUTOMOBILE_WORK_PROFILE_POLL_INTERVAL_MS |
Android work-profile package polling interval; positive integer milliseconds. | 5000 ms |
The daemon does background work only for devices that have a session. List
session-less devices in the three *_DEVICES variables above to include them,
for example when only an IDE is attached:
export AUTOMOBILE_IOS_WARMUP_DEVICES=00000000-0000-0000-0000-000000000001
export AUTOMOBILE_ANDROID_APPEARANCE_SYNC_DEVICES=emulator-5554
export AUTOMOBILE_ANDROID_OBSERVATION_STREAM_DEVICES=emulator-5554
AutoMobile does not create an emulator or simulator by default. To allow it:
export AUTOMOBILE_ALLOW_DEVICE_CREATE=1
auto-mobile --cli startDevice --platform ios --create-if-missing
Remove created devices with xcrun simctl delete <udid> or
avdmanager delete avd -n <name>.
Invalid AUTOMOBILE_EMULATOR_EXCLUDED_CONSOLE_PORTS entries fail at launch.
Session continuity is on by default for sessions bound to an Android emulator or iOS simulator. If the device connection disappears, AutoMobile keeps the session and waits for the same AVD or simulator UDID to come back. To turn that off:
export AUTOMOBILE_DEVICE_RECOVERY_ON_LOSS=0
AUTOMOBILE_DEVICE_RECOVERY_ON_LOSS=1 additionally restarts an Android emulator
that AutoMobile started with startDevice or getAndroid. AutoMobile never
restarts physical devices, emulators started outside AutoMobile, or iOS
simulators; it only waits for them. AUTOMOBILE_DEVICE_RECOVERY_MAX_ATTEMPTS
within AUTOMOBILE_DEVICE_RECOVERY_WINDOW_MS limits restarts.
Ambient Android and OS variables¶
Not AutoMobile-specific; these configure platform toolchains and the host.
| Variable | Use | Default |
|---|---|---|
ANDROID_HOME, ANDROID_SDK_ROOT, ANDROID_SDK_HOME |
Android SDK root used to find the emulator; the first that is set and exists wins. | unset |
HOME |
POSIX home directory; used to find the default Android SDK. | unset |
USERPROFILE |
Windows home directory, used when HOME is unset or empty. |
unset |
PATH |
Executable search path; reported in emulator-not-found diagnostics. | unset |
JAVA_HOME |
Java installation checked by doctor; its bin/java runs AUTOMOBILE_BUNDLETOOL_JAR. |
unset |
DEVELOPER_DIR |
Xcode developer directory used for the simulator profile cache. | xcode-select selection |
DISPLAY, WAYLAND_DISPLAY |
Linux display servers; when neither is set, emulators launch with -no-window. |
unset |
USER, LOGNAME |
POSIX account name (USER first), used to find the running emulator’s advertisement directory. |
unset |
XDG_RUNTIME_DIR |
Linux per-user runtime directory searched for running emulators. | unset |
TMPDIR |
Temporary directory; on Linux it takes precedence over XDG_RUNTIME_DIR for the private netsimd discovery file. |
unset |
NETSIM_ARGS |
Extra netsimd arguments; --no-shutdown is removed for private netsimd instances so each exits with its emulator. |
unset |
ANTHROPIC_API_KEY |
Anthropic API key used by vision features when none is configured explicitly. | unset |
ANDROID_USER_HOME, ANDROID_AVD_HOME, ANDROID_EMULATOR_HOME |
Android user, AVD and emulator home overrides used to locate AVD definitions. | unset |
ComSpec, COMSPEC |
Windows command interpreter used to run .bat Android tools (ComSpec first). |
cmd.exe |
LOCALAPPDATA |
Windows local app data directory used to find the default Android SDK. | unset |
Path |
Windows spelling of PATH, used when PATH is unset. |
unset |
PATHEXT |
Windows executable extensions used to locate bunx; only .com and .exe count. |
.COM;.EXE |
PUBLIC |
Windows public profile directory; head unit screenshots go there when the temp directory path has a space. | unset |
USERNAME |
Windows account name, used in the default daemon state-file names. | unset |
ADB_SERVER_SOCKET, ANDROID_ADB_SERVER_ADDRESS, ANDROID_ADB_SERVER_PORT |
The variables adb itself reads. AutoMobile uses them to identify the ADB server so daemons sharing one share device claims. The socket spec wins, then address and port. |
localhost:5037 |
GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR |
The variables git itself reads; a source build uses them to stamp its version. |
unset |
CTRL_PROXY_IOS_BUNDLE_ID, CTRL_PROXY_IOS_TIMEOUT |
Target app bundle id and runner lifetime in seconds, passed to the iOS CtrlProxy runner. | unset, 86400 |
MCP_SERVER_VERSION |
Override the reported MCP server version. | unset |
npm_package_version |
Package version exported by npm; used only when the manifest version is unavailable. | unset |
DEBUG_ADB_EXEC |
Any value logs adb execution with stack traces. | unset |
EMULATOR_POLLING_INTERVAL_MS |
Emulator readiness polling interval in milliseconds; minimum 100. |
500 |
Boot capacity¶
AutoMobile checks emulator and simulator cold boots against host capacity by default. Boot capacity explains each platform’s limit and the fields a refusal carries; see also iOS Simulator fleet cost. Adopting an emulator or simulator that is already running is never refused. A refused Android boot looks like this:
{
"success": false,
"error": "Refused to boot: no emulator capacity (code capacity_exhausted, retryable; retry after 5000ms): 2 emulator(s) booted; limit is 2 (derived). 1 of them were not started by AutoMobile but still count toward the limit: emulator-5554. Shut one down, raise the limit with AUTOMOBILE_ANDROID_MAX_BOOTED or disable the gate with AUTOMOBILE_BOOT_CAPACITY_GATE=0.",
"code": "capacity_exhausted",
"retryable": true,
"retryAfterMs": 5000,
"limit": 2,
"booted": 2,
"platform": "android",
"externalDevices": ["emulator-5554"]
}
The Android limit is shared by every daemon using the same ADB server on one
host. Daemons given different AUTOMOBILE_ADB_SERVER_COORDINATION_DIR values do
not see each other’s boots, so they can exceed the limit. Give each its own ADB
server as well to isolate their limits.
export AUTOMOBILE_ANDROID_MAX_BOOTED=3 # fixed Android limit
export AUTOMOBILE_IOS_SIM_MAX_BOOTED=2 # fixed iOS limit
export AUTOMOBILE_BOOT_CAPACITY_GATE=0 # turn the gate off on both platforms
export AUTOMOBILE_IOS_SIM_CAPACITY_GATE=0 # turn it off for iOS only
Shared ADB server¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_MANAGED_ADB_SERVER, AUTO_MOBILE_MANAGED_ADB_SERVER |
Declare that this process owns the ADB server so a clean shutdown stops it; 1/true enables. |
off |
By default AutoMobile leaves the local ADB server running. Set
AUTOMOBILE_MANAGED_ADB_SERVER=1 only when this process owns the server; a clean
shutdown then stops it after active device sessions are released.
Port allocation¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_PORT_RANGE_START, AUTO_MOBILE_PORT_RANGE_START |
First CtrlProxy host port; positive integer. | 8765 |
AUTOMOBILE_PORT_RANGE_END, AUTO_MOBILE_PORT_RANGE_END |
Last CtrlProxy host port (inclusive), at least the start. Takes precedence over size; invalid values fall back to 100 ports. | unset |
AUTOMOBILE_PORT_RANGE_SIZE, AUTO_MOBILE_PORT_RANGE_SIZE |
Number of CtrlProxy host ports; positive integer, used only without an end. | 100 |
AUTOMOBILE_PORT_REVERSE_ALLOWED_PORTS |
Ports portReverse may map, device and host side: comma-separated ports or inclusive ranges, e.g. 3000-3999,8080. Any invalid entry allows nothing. Ports below 1024 are always refused. |
unset (1024-65535) |
AUTOMOBILE_PORT_REVERSE_RECONCILE_INTERVAL_MS |
Milliseconds between periodic re-checks that re-add owned portReverse mappings removed outside AutoMobile; integer of at least 1000. Anything else is ignored with a warning. |
30000 ms |
Assets and CtrlProxy¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_VERSION |
Release version of downloaded assets; unset, empty or latest uses the newest release. Unknown pins fail integrity checks. |
newest release |
AUTOMOBILE_ASSET_BASE_URL |
Release asset mirror; absolute HTTPS URL without query or fragment. | https://github.com/kaeawc/auto-mobile/releases/download |
AUTOMOBILE_PROTOTYPE_CUSTOM_SHADERS |
Enable Android prototype AGSL shaders with exactly 1; requires a device advertising prototype_custom_shaders_v1. |
off |
AUTOMOBILE_ALLOW_INSECURE_ASSET_URL |
Permit plaintext HTTP asset URLs; 1/true enables. |
off |
AUTOMOBILE_CTRL_PROXY_APK_PATH |
Use a local Android CtrlProxy APK instead of the released one; filesystem path. Skips the published checksum check. | released/cached APK |
AUTOMOBILE_SKIP_ACCESSIBILITY_CHECKSUM, AUTO_MOBILE_ACCESSIBILITY_SERVICE_SHA_SKIP_CHECK |
Skip Android APK checksum checks; 1/true enables. |
off |
AUTOMOBILE_SKIP_ACCESSIBILITY_DOWNLOAD_IF_INSTALLED |
Accept an already-installed APK without checking it during auto-setup and doctor; 1/true enables. Device readiness still upgrades a mismatched APK. |
off |
AUTOMOBILE_SKIP_CTRL_PROXY_DOWNLOAD |
Use local CtrlProxy sources instead of downloading; 1/true enables. |
off |
AUTOMOBILE_EAGER_PREFETCH |
Fully recheck the cached Android CtrlProxy APK (zip and SHA-256) at each start, even when it is unchanged since its last check; 1/true enables. |
off |
AUTOMOBILE_IOS_CAMERA_POSTER_DYLIB |
Prebuilt iOS Simulator camera-poster injection library; must name an existing file. | build on demand |
AUTOMOBILE_IOS_CAMERA_POSTER_SOURCE |
Source file for building the iOS Simulator camera-poster library, replacing the one shipped in the package. | shipped in the package |
AUTOMOBILE_IOS_PROTOTYPE_AGENT |
Local iOS simulator prototype-agent dylib; filesystem path that must exist. | local build, then verified release download |
AUTOMOBILE_SKIP_IOS_PROTOTYPE_AGENT_DOWNLOAD |
Do not download the prototype-agent dylib when no verified cached copy exists; 1/true enables. |
off |
AUTOMOBILE_IOS_PROTOTYPE_VIEWER |
Local viewer template; app directory containing Info.plist, relative to the daemon launch directory. Invalid values fail. |
local build, then verified release download |
AUTOMOBILE_ANDROID_PROTOTYPE_APP_TEMPLATE |
Android disposable-app template; directory holding the template flavor (template.apk, AndroidManifest.xml, template.json, capabilities.json). Invalid values fail. |
none (released template not published yet) |
AUTOMOBILE_SKIP_IOS_PROTOTYPE_VIEWER_DOWNLOAD |
Do not download the viewer template when no verified cache exists; 1/true enables. |
off |
AUTOMOBILE_CTRLPROXY_VERBOSE |
Verbose iOS CtrlProxy output; 1/true enables. |
off |
AUTOMOBILE_CTRL_PROXY_HEALTH_MAX_ATTEMPTS, AUTO_MOBILE_CTRL_PROXY_HEALTH_MAX_ATTEMPTS |
iOS runner health poll attempts; positive integer. | 60 |
AUTOMOBILE_IOS_RUNNER_LAUNCH_CONCURRENCY |
Maximum concurrent iOS runner launches per daemon; positive integer. Invalid values use the default. | 2 |
AUTOMOBILE_IPROXY_START_TIMEOUT_MS, AUTO_MOBILE_IPROXY_START_TIMEOUT_MS |
iOS USB iproxy tunnel startup timeout; positive integer milliseconds. | 5000 ms |
AUTOMOBILE_CWEBP_PATH |
Trusted cwebp executable; filesystem path. An invalid executable fails. |
PATH, bundled or downloaded libwebp |
AUTOMOBILE_DWEBP_PATH |
Trusted dwebp executable; filesystem path. An invalid executable fails. |
PATH, bundled or downloaded libwebp |
AUTOMOBILE_FFMPEG |
ffmpeg executable path or name. |
ffmpeg on PATH |
To keep an installed CtrlProxy APK through device readiness, set
AUTOMOBILE_SKIP_CTRL_PROXY_DOWNLOAD=1 together with
AUTOMOBILE_SKIP_ACCESSIBILITY_CHECKSUM=1.
Queued iOS runner launches¶
When simultaneous cold iOS observe calls exceed
AUTOMOBILE_IOS_RUNNER_LAUNCH_CONCURRENCY, a read can return before its runner
starts. See Cold iOS observe freshness
for the result. A readiness: none observe reports the same way when its read
lapses with a timeout, setup failure, or recovery reason while the device’s launch
is queued or holds a launch slot. Retry the observe shortly.
iOS builds and signing¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_PROJECT_ROOT |
Root used by local iOS CtrlProxy source builds; filesystem path. | process working directory |
AUTOMOBILE_CTRL_PROXY_IOS_DERIVED_DATA |
Derived-data root for local iOS CtrlProxy builds; filesystem path. | data directory derived-data |
AUTOMOBILE_TVOS_RUNNER_XCTESTRUN |
Prebuilt tvOS simulator runner xctestrun path used by startDevice; its containing directory must be writable. |
discovered locally, downloaded from the release, or built from source |
AUTOMOBILE_VISIONOS_RUNNER_XCTESTRUN |
Prebuilt visionOS window-app runner xctestrun path used on first observe, tapOn or sendKeys; its containing directory must be writable. |
discovered locally, downloaded from the release, or built from source |
AUTOMOBILE_WATCH_RUNNER_XCTESTRUN |
Prebuilt watchOS simulator runner xctestrun path used by startDevice; its containing directory must be writable. |
discovered locally, downloaded from the release, or built from source |
AUTOMOBILE_CTRL_PROXY_IOS_CACHE_DIR |
iOS CtrlProxy bundle cache; filesystem path. | coordination directory ctrl-proxy-ios |
AUTOMOBILE_CTRL_PROXY_IOS_BUNDLE_URL |
Custom iOS bundle download URL; HTTPS unless the insecure asset URL opt-in is set. | release bundle URL |
AUTOMOBILE_CTRL_PROXY_IOS_IPA_PATH |
Local iOS archive or bundle; filesystem path. Wins over the bundle-path override. | released bundle |
AUTOMOBILE_CTRL_PROXY_IOS_BUNDLE_PATH |
Local iOS runner bundle or archive; filesystem path. | released bundle |
AUTOMOBILE_CTRL_PROXY_IOS_RUNNER_SHA256 |
Expected 64-character hex SHA256 of a local or custom runner executable. | release checksum |
AUTOMOBILE_CTRL_PROXY_IOS_RUNNER_SHA256_TARGET |
Which executable the checksum applies to: exact runner or xctest. |
release target |
AUTOMOBILE_CTRL_PROXY_IOS_USE_LOCAL_BUILD |
Pin the hash of a local build after it is built, and reverify it before launch; 1/true enables. |
off |
AUTOMOBILE_IOS_CTRL_PROXY_APP_HASH |
Expected device app bundle hash; the device-specific variable wins. | released device app hash |
AUTOMOBILE_IOS_CTRL_PROXY_APP_HASH_DEVICE |
Expected device app bundle hash. | generic override or released hash |
AUTOMOBILE_IOS_CTRL_PROXY_APP_HASH_SIMULATOR |
Expected simulator app bundle hash. | unset; not verified |
AUTOMOBILE_IOS_SKIP_CTRL_PROXY_APP_HASH |
Skip iOS app bundle hash checks; 1/true enables. |
off |
AUTOMOBILE_IOS_HELPER_REQUIRE_CODESIGN |
Make codesign, Gatekeeper or Team ID failures fatal; 1/true enables. |
off; failures warn |
AUTOMOBILE_IOS_HELPER_TEAM_ID |
Apple Team ID to verify on the downloaded runner bundle. | unset |
AUTOMOBILE_IOS_TEAM_IDS |
Comma-separated signing Team IDs; wins over the single Team ID. | auto-detected |
AUTOMOBILE_IOS_TEAM_ID |
Single signing Team ID (a comma-separated list also works). | auto-detected |
AUTOMOBILE_IOS_PROFILE_UUID |
Provisioning profile UUID; wins over name and specifier. | automatic discovery |
AUTOMOBILE_IOS_PROFILE_NAME |
Provisioning profile name; wins over specifier. | automatic discovery |
AUTOMOBILE_IOS_PROFILE_SPECIFIER |
Provisioning profile specifier. | automatic discovery |
AUTOMOBILE_IOS_CODE_SIGN_IDENTITY |
Signing identity. | auto-detected |
AUTOMOBILE_IOS_CODE_SIGN_ENTITLEMENTS_PATH |
Entitlements file for signing; filesystem path. | automatic discovery |
Video recording and capture¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_VIDEO_QUALITY_PRESET, AUTO_MOBILE_VIDEO_QUALITY_PRESET |
Recording preset: exact low, medium, high. CLI and per-call options win. |
low |
AUTOMOBILE_VIDEO_TARGET_BITRATE_KBPS, AUTO_MOBILE_VIDEO_TARGET_BITRATE_KBPS |
Target bitrate in kbps; positive integer. Invalid values warn and are ignored. The throughput cap may lower it. | 1000 kbps |
AUTOMOBILE_VIDEO_MAX_THROUGHPUT_MBPS, AUTO_MOBILE_VIDEO_MAX_THROUGHPUT_MBPS |
Recording throughput cap in Mbps; positive number. Invalid values warn and are ignored. | 5 Mbps |
AUTOMOBILE_VIDEO_FPS, AUTO_MOBILE_VIDEO_FPS |
Frames per second; positive integer. The device may clamp it. | 15 fps |
AUTOMOBILE_VIDEO_MAX_ARCHIVE_MB, AUTO_MOBILE_VIDEO_MAX_ARCHIVE_MB |
Recording archive size limit in MB; positive number. | 100 MB |
AUTOMOBILE_VIDEO_FORMAT, AUTO_MOBILE_VIDEO_FORMAT |
Exact mp4; other values warn and are ignored. |
mp4 |
AUTOMOBILE_VIDEO_RETENTION_DAYS, AUTO_MOBILE_VIDEO_RETENTION_DAYS |
Days to keep recordings; nonnegative number, 0 disables age expiry. |
7 days |
AUTOMOBILE_VIDEO_RETENTION_SWEEP_MINUTES, AUTO_MOBILE_VIDEO_RETENTION_SWEEP_MINUTES |
How often expired recordings are removed, in minutes; positive number. | 60 minutes |
AUTOMOBILE_VIDEO_INPROGRESS_CHECK_SECONDS, AUTO_MOBILE_VIDEO_INPROGRESS_CHECK_SECONDS |
How often an active recording’s size is checked, in seconds; positive number. | 15 seconds |
AUTOMOBILE_ANDROID_VIDEO_USE_FFMPEG_PIPE |
Record Android video by piping screenrecord through ffmpeg; 1/true enables. |
off |
AUTOMOBILE_VIDEO_SERVER_JAR |
Local Android video encoder JAR; filesystem path, used only if it exists. | cached/released JAR, then source build |
AUTOMOBILE_REQUIRE_VIDEO_SERVER |
Fail when the video encoder JAR is unavailable instead of degrading; 1/true enables. |
off |
AUTOMOBILE_SKIP_VIDEO_SERVER_DOWNLOAD |
Resolve the video encoder JAR locally only; 1/true enables. |
off |
AUTOMOBILE_IOS_SCREEN_CAPTURE_HELPER, AUTO_MOBILE_IOS_SCREEN_CAPTURE_HELPER |
Local screen-capture helper executable; filesystem path. | released helper |
AUTOMOBILE_IOS_AUDIO_LOOPBACK_HELPER |
Local audio-loopback helper executable for iOS Simulator injectAudioInput and captureAudio; filesystem path. |
unset: simulator audio unavailable |
AUTOMOBILE_CARPLAY_POWER_HELPER_PATH |
Local carplay-power-helper executable that turns on the iOS 26 Simulator CarPlay screen; filesystem path. | unset: helper unavailable |
AUTOMOBILE_CARPLAY_PROJECTION_PROBE_PATH |
Local CarPlay projection probe executable that startDevice carPlay runs in the simulator; absolute path. |
unset: probe unavailable |
AUTOMOBILE_NETWORK_FILTER_APP_PATH |
Local signed Network Filter .app for auto-mobile --ios-network-filter install. |
release download |
AUTOMOBILE_NETWORK_FILTER_TEAM_ID |
Apple Team ID the Network Filter app and its provider must both be signed by. | shared Developer ID team required |
AUTOMOBILE_IOS_SIMULATOR_WINDOW_TIMEOUT_MS |
How long to wait to find the simulator window for capture; positive integer milliseconds. | 2000 ms |
WebRTC¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_WEBRTC_WHIP_ENDPOINT |
WHIP ingest URL; HTTPS, or loopback HTTP. Remote HTTP requires the insecure-WHIP opt-in. Per-call options win. | unset; required to stream |
AUTOMOBILE_WEBRTC_WHIP_TOKEN |
Bearer token for WHIP ingest. | unset |
AUTOMOBILE_WEBRTC_ICE_SERVERS |
JSON array of RTCIceServer objects (urls, optional username/credential) or comma-separated STUN/TURN URLs. |
stun:stun.l.google.com:19302 |
AUTOMOBILE_WEBRTC_BITRATE_KBPS |
Encoder bitrate in kbps; positive number. | encoder/source default |
AUTOMOBILE_WEBRTC_MAX_SIZE |
Maximum frame size as WIDTHxHEIGHT; positive even integers within the H.264 Level 4.2 limit. |
source dimensions |
AUTOMOBILE_WEBRTC_IOS_SIMULATOR_FPS |
iOS simulator capture rate; integer 5..60. |
15 fps |
AUTOMOBILE_WEBRTC_ANDROID_FPS |
Android capture rate; integer 1..60. |
30 fps |
AUTOMOBILE_WEBRTC_TRICKLE_ICE |
Use WHIP PATCH trickle ICE; 1, true, yes, on enable. |
off |
AUTOMOBILE_WEBRTC_AUDIO |
Add an audio track; 1, true, yes, on enable. |
off |
AUTOMOBILE_WEBRTC_ALLOW_INSECURE_WHIP |
Permit non-loopback HTTP and arbitrary per-call WHIP overrides; 1, true, yes, on enable. |
off |
AUTOMOBILE_WEBRTC_WHIP_ALLOWED_ORIGINS |
Comma-separated origins or bare host[:port] allowed for per-call WHIP overrides. Loopback and the configured WHIP origin are always allowed. |
empty |
Navigation retention¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_NAV_RETENTION_SCREENSHOT_TTL_MS |
How long navigation screenshots are kept; positive integer milliseconds. | 604800000 ms (7 days) |
AUTOMOBILE_NAV_RETENTION_STRUCTURE_TTL_MS |
How long navigation structure is kept; positive integer milliseconds. | 7776000000 ms (90 days) |
AUTOMOBILE_NAV_RETENTION_PER_APP_MAX_OBSERVATIONS |
Observation cap per app; positive integer. | 50000 |
AUTOMOBILE_NAV_RETENTION_GLOBAL_MAX_OBSERVATIONS |
Observation cap across all apps; positive integer. | 500000 |
AUTOMOBILE_NAV_RETENTION_EVICTION_CHUNK_SIZE |
Rows removed per cleanup batch; positive integer, at most 10000. |
5000 |
AUTOMOBILE_NAV_RETENTION_INTERVAL_MS |
How often cleanup runs; positive integer milliseconds, at most 2147483647. |
21600000 ms (6 hours) |
Performance diagnostics¶
| Variable | Use and accepted values | Default |
|---|---|---|
AUTOMOBILE_OBSERVE_PERF_SNAPSHOT, AUTO_MOBILE_OBSERVE_PERF_SNAPSHOT |
Attach a rolling performance snapshot to observe results; 1/true enables. |
off |
AUTOMOBILE_OBSERVE_PERF_WINDOW_MS, AUTO_MOBILE_OBSERVE_PERF_WINDOW_MS |
Snapshot window in milliseconds, clamped to 1000..30000; invalid values fall back. |
5000 ms |
AUTOMOBILE_DISABLE_PERF_AUDIT |
Disable the UI performance audit; 1/true disables. |
off |
AUTOMOBILE_TOUCH_LATENCY_SAMPLING |
Sample synthetic tap latency; 1/true enables. |
off |
AUTOMOBILE_TRACE_PROCESSOR |
Perfetto trace_processor_shell used to summarize Android performanceTrace traces; path or command name. |
trace_processor_shell on PATH |
Testing and internal¶
AutoMobile reads these for testing and diagnostics; they are not for normal use.
| Variable | Use | Default |
|---|---|---|
AUTOMOBILE_HARNESS_PRIVATE_DAEMON |
Marks a daemon as a short-lived private test daemon: 1 arms the orphan watchdog, 0 exempts it. |
unset |
AUTOMOBILE_DAEMON_LAUNCHER_PID |
Pid of the process that launched a private test daemon, for the orphan watchdog. | parent pid |
AUTOMOBILE_PRIVATE_DAEMON_ORPHAN_IDLE_MS |
Idle time after which an orphaned private test daemon exits; milliseconds, 0 disables. |
900000 ms |
AUTOMOBILE_IOS_CTRLPROXY_RECORD_DIR |
Record iOS CtrlProxy requests and responses as JSON in this directory; filesystem path. | off |
AUTOMOBILE_IOS_TAP_STRATEGY |
Diagnostic iOS tap strategy, at debug log level only: legacy, appRelative, appRelativeObserved, displayTargeted, displayTargetedObserved. |
runner default |
AUTOMOBILE_UNIT_TEST_ISOLATED_DATA_DIR |
Data directory isolated by the unit-test preload. | unset |
CI, GITHUB_ACTIONS |
Both exactly true on a GitHub Actions runner, where AutoMobile owns the iOS simulator lifecycle. |
unset |
GITHUB_WORKSPACE |
GitHub Actions checkout directory, searched for schemas/test-plan.schema.json. |
unset |
NODE_ENV |
Exact test arms the test-only guards and test defaults. |
unset |
Do not use AUTOMOBILE_DB_PATH=:memory: in production. Tests may allow it by also setting
AUTOMOBILE_ALLOW_IN_MEMORY_DB to 1, true or yes.
Template cloning is off by default; opt in with AUTOMOBILE_IOS_TEMPLATE_CLONE=1.
The first request then uses normal creation and starts a background template build.
Later requests can clone a settled, shut-down template for the same runtime, device
type and preboot profile. Template builds take a boot capacity slot and may take
several minutes.
Template commands require macOS and work whether or not cloning is on:
| Command | Effect |
|---|---|
auto-mobile --ios-templates build --runtime <identifier> --device-type <identifier> |
Build one template. |
auto-mobile --ios-templates clean --all |
Remove every template. |
auto-mobile --ios-templates clean --runtime <identifier> --device-type <identifier> |
Remove one template. |
The selected template uses the preboot profile from
AUTOMOBILE_IOS_PREBOOT_LEAN_PROFILE. Cleanup refuses active builds unless you pass
--force. A failed or deferred build exits with status 1; successful build and
cleanup exit 0.