Command reference

For anyone who runs the farm from a terminal or a script. Every command of sf, with its usage, options and an example. sf <command> --help prints the same text for one command.

Conventions#

sf has two kinds of commands. Local commands (doctor, host, config, token, serve, service, version, completion) work on the machine and need no daemon. All others talk to the daemon over HTTP, so the daemon must be running (sf serve or sf service start).

A selector picks Androids. It is one of all, running, stopped, tag:NAME, a number such as 5, or a range such as 1-10. Join selectors with commas and exclude with !, for example 1-10,tag:eu,!tag:spare.

Exit codes: 0 success, 1 the operation failed, 2 wrong usage, 130 interrupted with Ctrl-C. sf doctor exits 1 when a check fails, and sf service status exits 3 when the service is not active.

The global options below are accepted before and after the command name (sf --json ls and sf ls --json are the same).

Commands#

sf ls#

Alias: sf list.

List the Androids and their state.

sf ls [-w] [--interval SECONDS]

Example:

sf ls
sf ls -w

sf create#

Add one or more Androids. Anything not given follows the farm's settings (sf config show) and keeps following them when they change.

sf create [-n COUNT] [--name NAME] [--android VERSION]
          [--gpu {auto,software,igpu,dgpu,intel,amd,nvidia}]
          [--net {direct,vpn,gateway,proxy,none}] [--vpn PROFILE] [--gateway NAME] [--cpus CPUS]
          [--memory MIB] [--width WIDTH] [--height HEIGHT] [--dpi DPI] [--fps FPS] [--tag TAG]
          [--data-volume VOLUME] [--image IMAGE]

Example:

sf create -n 5 --android 13 --gpu igpu --tag eu
sf create --name shop --net vpn --vpn nl-ams.ovpn

sf start#

Start Androids.

sf start [--force] selector

Example:

sf start 1-10

sf restart#

Restart Androids.

sf restart [--force] selector

Example:

sf restart tag:eu

sf recreate#

Rebuild the containers of Androids (data is kept).

sf recreate [--force] selector

Example:

sf recreate 3

sf stop#

Stop Androids.

sf stop selector

Example:

sf stop all

sf rm#

Alias: sf delete.

Delete Androids and, unless --keep-data, their data. With backup.auto_before_risky (the default) a backup is taken first.

sf rm [--keep-data] [--force] [-y] selector

Example:

sf rm 7
sf rm tag:test --keep-data --yes

sf set#

Change per-Android settings. Keys are InstanceSpec fields, nested ones with a dot (network.mode, resources.cpus, device.locale). Lists are comma separated. default puts an optional setting back to following the farm's value.

sf set [--force] selector key=value [key=value ...]

Example:

sf set 1-5 fps=30 network.mode=vpn tags=eu,shop
sf set 3 gpu_mode=default

sf info#

Show one Android in detail.

sf info [--device] id

Example:

sf info 3

sf logs#

Show the container logs of one Android.

sf logs [-n LINES] [--logcat] id

Example:

sf logs 3 -n 50
sf logs 3 --logcat

sf gpu#

GPUs and the rendering mode of Androids.

sf gpu ls#

List GPUs and the rendering choices on this machine.

sf gpu ls

Example:

sf gpu ls

sf gpu set#

Choose how Androids draw (applied at their next restart).

sf gpu set [--node DEVICE] selector {auto,software,igpu,dgpu,intel,amd,nvidia,default}

Example:

sf gpu set 1-8 igpu
sf gpu set 9 nvidia --node /dev/dri/renderD129

sf image#

Android images, one per Android version.

sf image ls#

List the image of every configured Android version.

sf image ls

Example:

sf image ls

sf image pull#

Download and prepare the image of one Android version.

sf image pull version

Example:

sf image pull 13

sf image build#

Rebuild an image with its overlays (camera, GPU runtime).

sf image build version

Example:

sf image build 13

sf tasks#

List background tasks, or show, follow and cancel one.

sf tasks [--active] [--cancel] [id]

Example:

sf tasks
sf tasks t12 --wait
sf tasks t12 --cancel

sf top#

Live load of the host, the GPUs and every running Android.

sf top [--interval SECONDS] [--once]

Example:

sf top

sf open#

Print the panel's address and how to log in.

sf open

Example:

sf open

sf shell#

Run one command on every selected Android and show each one's output. The words after -- are the command, passed as separate arguments (no shell on this machine ever sees them). Obviously destructive commands are refused unless --force.

sf shell [--root] [--timeout SECONDS] [--force] selector

Example:

sf shell all -- getprop ro.build.version.release
sf shell 3 --root -- ls /data/app

sf screenshot#

Save a screenshot of one Android.

sf screenshot [-o FILE] id

Example:

sf screenshot 3 -o shot.png

sf apps#

The app library: APK / XAPK / APKS / APKM files kept by the farm.

sf apps ls#

List the apps in the library.

sf apps ls

Example:

sf apps ls

sf apps add#

Upload an app file into the library.

sf apps add FILE [FILE ...]

Example:

sf apps add ~/Downloads/shop-4.2.apk

sf apps rm#

Remove an app from the library.

sf apps rm app_id

Example:

sf apps rm com.example.shop-42

sf app#

Apps on the Androids: install, launch, stop, clear, compare versions.

sf app install#

Install an app from the library.

sf app install [--no-grant] [--downgrade] selector app

Example:

sf app install 1-10 com.example.shop

sf app ensure#

Install an app only where it is missing or older.

sf app ensure [--no-grant] selector app

Example:

sf app ensure all com.example.shop

sf app uninstall#

Remove an app.

sf app uninstall [--keep-data] selector package

Example:

sf app uninstall tag:test com.example.shop

sf app launch#

Open an app.

sf app launch selector package

Example:

sf app launch all com.example.shop

sf app stop#

Force-stop an app.

sf app stop selector package

Example:

sf app stop all com.example.shop

sf app clear#

Erase an app's data (as after a fresh install).

sf app clear selector package

Example:

sf app clear 3 com.example.shop

sf app matrix#

Which version of which app is installed where.

sf app matrix [selector]

Example:

sf app matrix running

sf push#

Copy a local file onto Androids.

sf push selector local [remote]

Example:

sf push all notes.txt /sdcard/Download/

sf pull#

Copy a file from one Android to this machine.

sf pull [-o PATH] id remote

Example:

sf pull 3 /sdcard/Download/report.pdf

sf gallery#

Add a picture or video to the gallery of Androids.

sf gallery selector local

Example:

sf gallery 1-5 photo.jpg

sf input#

Send the same touch or key to many Androids at once.

sf input tap#

Tap one point on every selected Android. Coordinates are fractions of the screen (0.5 0.9 = centre, near the bottom), so one command fits every resolution.

sf input tap [--pixels] selector x y

Example:

sf input tap 1-10 0.5 0.9

sf input text#

Type text into the focused field.

sf input text selector text

Example:

sf input text 3 'hello world'

sf input key#

Press a key.

sf input key selector key

Example:

sf input key all HOME

sf window#

Native device windows (scrcpy) on the desktop the daemon runs on.

sf window open#

Open a window for each selected Android.

sf window open selector

Example:

sf window open 3

sf window grid#

Open windows tiled to fill the screen.

sf window grid selector

Example:

sf window grid 1-12

sf window close#

Close device windows.

sf window close selector

Example:

sf window close all

sf vpn#

VPN profiles, logins and tunnel status.

sf vpn profiles#

List the imported VPN profiles.

sf vpn profiles

Example:

sf vpn profiles

sf vpn import#

Import OpenVPN (.ovpn) or WireGuard (.conf) profiles.

sf vpn import FILE [FILE ...]

Example:

sf vpn import ~/vpn/nl-ams.ovpn ~/vpn/de-fra.ovpn

sf vpn rm#

Remove a VPN profile.

sf vpn rm name

Example:

sf vpn rm nl-ams.ovpn

sf vpn credentials#

Store a VPN login under a name (network.vpn.credentials says which name profiles use; default unless changed). The password is asked for without echo, or read from stdin with --password-stdin; it is never taken from the command line. Stored logins cannot be read back, only replaced or deleted. Without a name: list the names that exist.

sf vpn credentials [--username USERNAME] [--password-stdin] [--delete] [name]

Example:

sf vpn credentials default
printf '%s' "$VPN_PASSWORD" | sf vpn credentials default --username myaccount --password-stdin

sf vpn status#

Tunnel state, public address and kill switch of Androids.

sf vpn status [--refresh] [selector]

Example:

sf vpn status running
sf vpn status 3 --refresh

sf gateway#

Shared VPN gateways: one tunnel for many Androids.

sf gateway ls#

List gateways and their state.

sf gateway ls

Example:

sf gateway ls

sf gateway add#

Define a gateway (or change an existing one).

sf gateway add --profile PROFILE [--provider {openvpn,wireguard}] [--credentials CREDENTIALS]
               [--subnet SUBNET]
               name

Example:

sf gateway add eu --profile nl-ams.ovpn

sf gateway rm#

Remove a gateway (asks first).

sf gateway rm [--force] [-y] name

Example:

sf gateway rm eu

sf gateway up#

Start a gateway and wait for its tunnel.

sf gateway up name

Example:

sf gateway up eu

sf gateway down#

Stop a gateway.

sf gateway down [--force] name

Example:

sf gateway down eu

sf camera#

Feed a video or live stream into the camera and microphone of Androids.

sf camera status#

Show whether the virtual camera is ready, what plays where, and the sources.

sf camera status

Example:

sf camera status

sf camera play#

Play a media file (or the live RTMP ingest) as the camera of Androids.

sf camera play [--sound SOUND] selector source

Example:

sf camera play 1-5 intro.mp4
sf camera play 3 rtmp --sound none

sf camera stop#

Stop the camera feed.

sf camera stop [selector]

Example:

sf camera stop 1-5

sf camera mic#

Mute, unmute or solo the microphone of Androids.

sf camera mic selector {mute,unmute,solo}

Example:

sf camera mic 3 solo

sf listen#

Hear one Android on the speakers of the machine the daemon runs on.

sf listen [ID|off]

Example:

sf listen 3
sf listen off

sf auto#

Automation. Record a task a few times in the panel, train the recordings into a program (sf auto train), then run it on any selection of Androids (sf auto run). Flows are hand-written YAML scripts run the same way.

sf auto datasets#

List datasets (groups of recordings of one task).

sf auto datasets

Example:

sf auto datasets

sf auto train#

Turn a dataset's recordings into one program.

sf auto train dataset

Example:

sf auto train open-settings

sf auto programs#

List trained programs.

sf auto programs

Example:

sf auto programs

sf auto flows#

Hand-written YAML flows (bare: list them).

sf auto flows ls#

List flows, including the shipped examples.

sf auto flows ls

Example:

sf auto flows ls

sf auto flows show#

Print a flow's YAML.

sf auto flows show name

Example:

sf auto flows show examples/open-app

sf auto flows validate#

Check a YAML file without saving it.

sf auto flows validate file

Example:

sf auto flows validate login.yaml

sf auto flows save#

Save a YAML file as a flow (validated first).

sf auto flows save name file

Example:

sf auto flows save login login.yaml

sf auto flows rm#

Delete a flow.

sf auto flows rm name

Example:

sf auto flows rm login

sf auto run#

Run a trained program or a flow on every selected Android, each on its own. A device that meets a screen no rule covers stops and waits (see sf auto runs <task> and sf auto resolve); the others carry on.

sf auto run [--var NAME=VALUE] [--secret NAME] [--dry-run] {program,flow} name selector

Example:

sf auto run flow examples/open-app 1-10 --var package=com.android.settings
sf auto run program sign-in tag:eu --var user=demo --secret password

sf auto runs#

List runs, or show one run device by device.

sf auto runs [--active] [task]

Example:

sf auto runs
sf auto runs t12

sf auto resolve#

Let a device that waits for attention continue, skip the step or stop.

sf auto resolve task id [{resume,skip,abort}]

Example:

sf auto resolve t12 4 resume

sf auto values#

Values that runs type in: shared, per Android, and pools (bare: list them).

sf auto values ls#

List stored values and pools.

sf auto values ls [--instance ID]

Example:

sf auto values ls
sf auto values ls --instance 3

sf auto values set#

Store a value under a name; flows and programs use it as {name}. Leave the value out to be asked for it without echo (or to pipe it in), so it never appears in the process list or in shell history. Names that look like secrets (password, pin, otp, ...) are refused by the farm: pass those per run with sf auto run --secret.

sf auto values set [--instance ID] name [value]

Example:

sf auto values set city Berlin
sf auto values set invite-code        (asked for, not shown)

sf auto values rm#

Remove a value.

sf auto values rm [--instance ID] name

Example:

sf auto values rm city

sf auto values pool-add#

Add lines to a pool (each line is handed out once).

sf auto values pool-add name file

Example:

sf auto values pool-add codes codes.txt

sf auto values pool-rm#

Delete a pool.

sf auto values pool-rm name

Example:

sf auto values pool-rm codes

sf auto schedule#

Recurring runs (bare: list them).

sf auto schedule ls#

List schedules.

sf auto schedule ls

Example:

sf auto schedule ls

sf auto schedule add#

Run a program or flow on a timetable.

sf auto schedule add [--every SECONDS] [--cron LINE] [--var NAME=VALUE] [--dry-run]
                     name {program,flow} target selector

Example:

sf auto schedule add nightly flow examples/open-app all --cron '0 3 * * *' --var package=com.android.settings

sf auto schedule rm#

Delete a schedule.

sf auto schedule rm id

Example:

sf auto schedule rm s3

sf auto schedule enable#

Switch a schedule on.

sf auto schedule enable id

Example:

sf auto schedule enable s3

sf auto schedule disable#

Switch a schedule off without deleting it.

sf auto schedule disable id

Example:

sf auto schedule disable s3

sf backup#

Back up and restore Androids and the farm's settings.

sf backup create#

Back up /data of every selected Android (tar + manifest with checksums). A running Android is stopped for the copy and started again when backup.stop_for_backup is on.

sf backup create selector

Example:

sf backup create 1-5

sf backup list#

Alias: sf backup ls.

List the backups.

sf backup list [--kind {android,farm,all}]

Example:

sf backup list

sf backup verify#

Check a backup against its recorded checksums.

sf backup verify [--deep] archive

Example:

sf backup verify android-3/20250101-040000

sf backup restore#

Without --over the backup becomes a NEW Android and nothing existing is touched. With --over ID that Android's data is replaced: it must be stopped, and you are asked first. A farm backup (farm/<time>) merges settings into this farm and never overwrites what exists. One this farm made itself is restored in full; from any other, only what cannot decide what runs on this machine is taken unless you say so with the flags below.

sf backup restore [--over ID] [--keep-network] [-y] [--trust] [--restore-config]
                  [--restore-secrets]
                  archive

Example:

sf backup restore android-3/20250101-040000
sf backup restore android-3/20250101-040000 --over 3
sf backup restore farm/20250101-050000

sf backup prune#

Delete old backups, keeping the newest backup.keep of each Android.

sf backup prune

Example:

sf backup prune

sf backup farm#

Back up the farm itself: settings, Android definitions, automation.

sf backup farm [--include-secrets]

Example:

sf backup farm

sf mcp#

Run the farm's MCP server. Alone, sf mcp speaks MCP over stdin/stdout: this is what a desktop assistant or IDE agent launches (see sf mcp config). With --http it serves Streamable HTTP on this machine only. Actions that change the farm follow ai.policy and wait for your Yes or No (sf approvals). Details: docs/MCP.md.

sf mcp config#

Print the mcpServers entry an MCP client needs to start this farm's server, with the absolute paths of this install. It never contains the API token.

sf mcp config [--http] [--port PORT]

Example:

sf mcp config
sf mcp config --http

sf mcp tools#

List the tools an assistant gets, with their class and what the policy does.

sf mcp tools [--markdown]

Example:

sf mcp tools
sf mcp tools --markdown

sf approvals#

An AI assistant that wants to change the farm waits for your Yes or No. Alone, sf approvals lists the requests.

sf approvals ls#

List approval requests, newest first.

sf approvals ls [--state {pending,approved,denied,expired}] [-n LIMIT]

Example:

sf approvals ls
sf approvals ls --state pending

sf approvals approve#

Say yes to a request: the action runs.

sf approvals approve [--remember] id

Example:

sf approvals approve 3f9a1c2e

sf approvals deny#

Say no to a request: nothing runs and the assistant is told.

sf approvals deny [--reason REASON] id

Example:

sf approvals deny 3f9a1c2e --reason 'not during business hours'

sf approvals watch#

Wait for approval requests and ask yes or no for each, until Ctrl-C.

sf approvals watch

Example:

sf approvals watch

sf ask#

Send one request to the farm's built-in Assistant and print its steps and its answer. Actions that change the farm follow ai.policy: under ask each one is shown and waits for y or n here (or in the panel). The last line is the farm's own record of what ran.

sf ask [--model MODEL] [--keep] request [request ...]

Example:

sf ask "how many Androids are running, and how many can this machine run?"
sf ask --model local "start every Android tagged eu"

sf ai#

Model profiles (which model, where), the built-in Assistant, and the AI Pilot, which turns a model operating an app into a program that replays without one. See docs/AI.md.

sf ai chat#

Talk with the built-in Assistant.

sf ai chat [--model MODEL]

Example:

sf ai chat
sf ai chat --model local

sf ai conversations#

List the Assistant's conversations.

sf ai conversations

Example:

sf ai conversations

sf ai models#

Model profiles: where a model lives and what it can do.

sf ai models ls#

List the configured profiles.

sf ai models ls

Example:

sf ai models ls

sf ai models test#

Really test a profile: server, model, a reply, a tool call.

sf ai models test name

Example:

sf ai models test local

sf ai models add#

Add or replace a profile.

sf ai models add --provider {ollama,openai} [--base-url BASE_URL] [--model MODEL]
                 [--key-name KEY_NAME] [--vision] [--no-tools] [--timeout TIMEOUT] [--default]
                 name

Example:

sf ai models add local --provider ollama --model <name> --default
sf ai models add hosted --provider openai --base-url https://api.example.com --model <name> --key-name hosted-key

sf ai models key#

Store a profile's API key (typed here, kept in secrets, never shown).

sf ai models key name

Example:

sf ai models key hosted

sf ai models rm#

Remove a profile.

sf ai models rm name

Example:

sf ai models rm hosted

sf ai pilot#

With a goal: start a Pilot session on the selected Androids. A model operates the app one action at a time and every action is recorded; a run counts only when the success check really holds. Train the recordings (--train, or sf ai pilot train) into a program that replays with no model: sf auto run program <dataset> <selector>.

With a word: sessions | show <session> | cancel <session> | resolve <session> <android> resume|skip|abort | confirm <session> <android> | train <dataset>.

sf ai pilot [--app PACKAGE] [--success CHECK] [--runs RUNS] [--model MODEL]
            [--max-steps MAX_STEPS] [--dataset DATASET] [--value NAME=VALUE] [--ask-value NAME]
            [--train] [--steps]
            GOAL SELECTOR | WORD ... [GOAL SELECTOR | WORD ... ...]

Example:

sf ai pilot "open the date and time settings" 1 --app com.android.settings --success "text:Set time automatically" --runs 3 --train
sf ai pilot sessions
sf ai pilot show t12 --steps
sf ai pilot resolve t12 3 resume
sf ai pilot confirm t12 3
sf ai pilot train open-the-date-and-time-settings

sf doctor#

Check that this machine can run Androids, with the fix for each problem.

sf doctor

Example:

sf doctor

sf host#

Prepare and inspect this machine (kernel modules, limits, GPUs).

sf host plan#

Show every command host setup would run, changing nothing.

sf host plan [--boot]

Example:

sf host plan

sf host apply#

Install packages, load kernel modules, raise kernel limits, create runtime folders and install the systemd units. Needs root: started as a normal user it continues under sudo, keeping your farm home. Safe to repeat.

sf host apply [--dry-run] [--boot]

Example:

sf host apply
sf host apply --dry-run

sf host capacity#

Estimate how many Androids this machine can run at once.

sf host capacity [--workload {video,light}]

Example:

sf host capacity

sf host gpus#

List the GPUs found and the rendering modes they allow.

sf host gpus

Example:

sf host gpus

sf host sign-module#

Run scripts/host/sign-module.sh. Without arguments it reports the Secure Boot state and the signing key in use. Arguments after -- go to the script (see its --help); anything but a status report runs under sudo.

sf host sign-module

Example:

sf host sign-module                              (status report)
sf host sign-module -- --create-key --enroll v4l2loopback

sf config#

Read and change the farm's settings (config.yaml).

sf config get#

Print one setting.

sf config get key

Example:

sf config get android.fps

sf config set#

Change one setting (validated before it is saved).

sf config set key value

Example:

sf config set android.fps 25
sf config set network.dns 1.1.1.1,9.9.9.9

sf config unset#

Put one setting back to its default.

sf config unset key

Example:

sf config unset android.fps

sf config show#

Print all settings in effect.

sf config show [--changed]

Example:

sf config show --changed

sf config path#

Print where config.yaml is.

sf config path

Example:

sf config path

sf config docs#

Render the settings reference (docs/CONFIGURATION.md).

sf config docs [-o FILE] [--check FILE]

Example:

sf config docs -o docs/CONFIGURATION.md
sf config docs --check docs/CONFIGURATION.md

sf token#

Print the API token the panel and scripts log in with.

sf token [--rotate]

Example:

sf token
sf token --rotate

sf serve#

Run the daemon in the foreground until Ctrl-C. Androids keep running when it stops.

sf serve [--host HOST] [--port PORT]

Example:

sf serve
sf serve --port 7701

sf service#

Run the daemon as a systemd user service.

sf service install#

Write and enable the user service.

sf service install

Example:

sf service install

sf service start#

Start the daemon in the background.

sf service start

Example:

sf service start

sf service stop#

Stop the daemon (Androids keep running).

sf service stop

Example:

sf service stop

sf service status#

Show whether the daemon runs.

sf service status

Example:

sf service status

sf service logs#

Show the daemon's log.

sf service logs [-n LINES] [-f]

Example:

sf service logs -f

sf version#

Print the version.

sf version

Example:

sf version

sf completion#

Print a shell completion script.

sf completion {bash,zsh}

Example:

sf completion bash > ~/.local/share/bash-completion/completions/sf
sf completion zsh > ~/.zfunc/_sf

Next#

• Quickstart shows the common commands in order.
• API reference lists the routes behind the client commands.
• Configuration reference lists every setting that sf config and sf set accept.
• Troubleshooting covers what to do when a command fails.