Architecture

For people who want to know how Super Farm is put together before they change it, debug it or trust it.

This page names the pieces, follows one start of an Android from the request to the booted device, and says where every kind of state lives. The reasons behind the design are in DESIGN_NOTES.md.

The pieces#

The daemon manages Androids and does not keep them alive. Stopping the daemon (Ctrl-C, SIGTERM, sf service stop) closes what the daemon itself started on the host, such as scrcpy windows and camera feeders. The Androids are Docker containers and keep running.

Inside the daemon, superfarm/farm.py is the composition root: one Farm object creates every component on first use and hands each to the others. A component that cannot be built (an optional tool is missing) reports itself as unavailable with the reason, and the rest keeps working.

The container pair#

One Android is two containers and a volume. The prefix comes from docker.name_prefix (default sf).

Every object carries the labels io.superfarm.farm=<prefix>, io.superfarm.instance=<N> and io.superfarm.role=<role>. The farm finds its own objects by label and never removes a container that lacks them.

Two rules govern the pair:

• The two containers are created and removed together, sidecar first. Android's network service rewrites the routing of the namespace it joins, so an Android recreated alone next to a running tunnel would drop that tunnel.
• Containers are rebuilt only when their plan changed. The planner turns the resolved settings into docker run arguments, and a digest of those arguments is stored on both containers as the label io.superfarm.plan. A start compares the digest and reuses the containers when it matches.

How a start works#

flowchart TD
    req["A start request: panel, sf start, API call, or an approved AI tool"]
    task["Daemon creates a task (one exclusive request per Android, a second one gets 409 busy)"]
    resolve["Resolve instance.yaml against config.yaml"]
    cap{"Is a stopped Android over the capacity estimate?"}
    refuse["Refuse with 409 over_capacity"]
    image["Make sure the image exists (pull the base, build the overlay)"]
    gpu["Choose the GPU and start the NVIDIA relay if this Android needs it"]
    net["Plan the sidecar, pick the VPN profile or bring the gateway up"]
    hash{"Plan digest equals the label on both containers?"}
    reuse["Stop the pair and start the existing sidecar"]
    rebuild["Remove both containers and create a new sidecar"]
    ready["Wait until the sidecar is ready (firewall verified, VPN tunnel up)"]
    android["Start the Android in the sidecar's network namespace"]
    boot["Wait for boot over ADB (performance.boot_timeout)"]
    post["After boot, apply identity, properties, animations, proxy, package trim, camera"]

    req --> task --> resolve --> cap
    cap -- "yes, and enforce_capacity is on without force" --> refuse
    cap -- "no, or warn only" --> image
    image --> gpu --> net --> hash
    hash -- "yes" --> reuse --> ready
    hash -- "no, or recreate" --> rebuild --> ready
    ready --> android --> boot --> post

The same steps as a list:

1. A request arrives: POST /api/instances/{id}/start or POST /api/instances/bulk. The panel, sf start, a script and an approved AI tool all end here.
2. The daemon submits a task and answers 202 with the task. Lifecycle work is exclusive per Android: while a task holds an Android, a second request for it is refused with 409 busy and the id of that task.
3. The instance spec (instances/<id>/instance.yaml) is resolved against config.yaml. Every value the spec leaves out follows the farm default.
4. If the Android is already running and this is a plain start, nothing is rebuilt. The start waits for boot, applies the post-boot settings and ends.
5. For a stopped Android the capacity estimate is asked. Over the estimate, the start warns and continues, or is refused when performance.enforce_capacity is on and the request carries no force.
6. The Android version about to boot is compared with the one that last booted this data volume. A downgrade is refused unless forced.
7. The image is made ready: an exact image if the spec names one, otherwise superfarm/android:<version>, built from the upstream base plus the files under <home>/overlays/android/<version>/.
8. CPU pinning and the GPU are chosen. For an NVIDIA choice the relay is started if it is not running.
9. The sidecar's arguments are planned. This builds the sidecar image when it is missing, picks and sanitises the VPN profile in vpn mode, and brings the shared gateway up in gateway mode.
10. Every refusal happens before this point. A refused restart leaves a running Android as it was.
11. The plan digest is compared with the label on the existing containers. If it matches, the pair is stopped and the same containers are started again, sidecar first. Otherwise both are removed and created anew.
12. If the renderer differs from the one this data last ran with, the apps' compiled shader caches are deleted from the volume first.
13. The sidecar starts: firewall, then DNS for the VPN server names, then the tunnel, then the route sync loop. The farm waits until the sidecar reports ready and its live firewall rules have been verified.
14. The Android container starts in the sidecar's network namespace.
15. The farm connects over ADB and waits for sys.boot_completed, up to performance.boot_timeout seconds.
16. Post-boot settings are applied: android_id, locale, time zone and mock location, extra properties, animation scales, the HTTP proxy in proxy mode, the one-time package trim, and the camera hook. Each is independent, and one that fails becomes a warning on the start result.

Stopping is the reverse: the Android container first, then the sidecar.

Networking topologies#

network.mode sets the farm default and each Android can override it.

A shared gateway named G is three objects:

sf-gw-G        the sidecar image running as a gateway server: one VPN client plus NAT; forwards members into the tunnel only
sf-gwnet-G     a bridge network with no NAT and no address on the host; a private /24 from docker.subnet_pool
sf-bridge      the farm's uplink network: carries the gateways' VPN transport and the members' published ADB ports

A member's sidecar sits on both networks. Its firewall lets only ADB answers out on the uplink and everything out on the gateway network, where the gateway container is the only router. One gateway holds at most 126 Androids.

Inside every sidecar a route sync loop runs every 2 seconds. Android's network daemon routes through its own per-interface table and removes routes it did not create, so the loop keeps the tunnel's routes in that table. NETWORKING.md describes the modes from the operator's side, and SECURITY_MODEL.md states what the kill switch guarantees.

The NVIDIA relay path#

Android's graphics stack is Mesa. Mesa drives Intel and AMD cards directly: the Android container gets the render node as a device and uses redroid's host GPU mode. Mesa has no driver for NVIDIA's proprietary stack, so an NVIDIA Android draws through a relay:

inside the Android
  GLES  -> ANGLE -> Vulkan
  Vulkan -> Mesa Venus driver (vulkan.virtio.so)
         -> Unix socket /venus/vtest.sock            bind-mounted from the host
on the host
  virgl_test_server --venus (patched) -> NVIDIA Vulkan driver -> the card

• One relay process runs per NVIDIA card, as your user. Its socket is <gpu.nvidia.socket_dir>/<node>/vtest.sock, and the folder is mounted into the Android at /venus.
• Four runtime files are bind-mounted read-only into each NVIDIA Android: the Venus driver, a 64-bit and a 32-bit allocator (gralloc.venus.so) and a gpu_config.sh with a venus mode. The Android image itself is not modified.
• The relay must run before an NVIDIA Android starts, and a running relay is never restarted, because every NVIDIA Android holds connections to it. The daemon's systemd unit uses KillMode=process so that a daemon restart leaves the relay alone.
• The runtime and the relay are built from native/venus/ into <home>/overlays/venus/ and <home>/overlays/venus-relay/. They are built for Android 13 only.

GPU.md covers choosing a mode and building the runtime.

Where state lives#

Everything the farm owns is under one home folder: $SUPERFARM_HOME, by default ~/.local/share/superfarm. A second home is a second, separate farm (give it another docker.name_prefix).

Outside the home:

Held in memory only, and lost when the daemon restarts: browser sessions, task history, the run status of automations, pending approval requests (they are expired at start) and "approve and remember" grants.

Requests, tasks and events#

• Every route is under /api and returns JSON. Errors have one shape: {"error": {"code", "message", "detail"}}.
• Work that touches several Androids or takes more than a moment runs as a task. The route answers 202 with the task, and GET /api/tasks/{id} or sf tasks <id> follows it. Each device has its own outcome, and one that fails or stalls does not hold up the others.
• WS /api/events pushes task and instance changes to the panel. It is a convenience: everything it reports can also be read by polling.
• POST /api/instances accepts an Idempotency-Key header, so a repeated create returns the first answer.

API.md is the route reference.

The tool registry#

superfarm/ai/tools.py holds one registry of 39 tools (17 read, 17 change, 5 destructive): name, description, JSON Schema for the arguments, class (read, change or destructive), a function that writes the one-line summary an operator approves, and the call itself. Each tool is a thin wrapper over API routes, so authentication, validation, capacity rules and the audit log apply to a model as they do to anyone else.

Two consumers use the registry, and both go through the same function, invoke():

• superfarm/mcp/server.py serves it to external MCP clients over stdio or loopback HTTP. It is the only module that imports the MCP SDK.
• superfarm/ai/assistant.py is the built-in Assistant. It calls invoke() directly, over the same API.

For a tool that changes the farm, invoke() asks the daemon (POST /api/approvals). The daemon applies ai.policy, writes the summary and, under ask, queues a request that waits for the operator's Yes or No. MCP.md and AI.md describe this from the operator's side.

Module map#

All paths are under superfarm/.

Foundation#

core#

host#

net#

The scripts that run inside the sidecar are in deploy/docker/net/: entrypoint.sh, killswitch.sh, routesync.sh and healthcheck.sh.

control, stream and media#

automation#

ai and mcp#

api, cli and web#

Outside the package: deploy/ (Dockerfiles and systemd unit templates), scripts/ (camera helpers, the module signing script, the quality gate), native/ (sources and patches for the NVIDIA runtime, the camera overlay and the camera kernel module) and tests/ (unit, live and distribution tests).

Next#

• DESIGN_NOTES.md: why it is built this way
• SECURITY_MODEL.md: trust boundaries and listeners
• CONFIGURATION.md: every setting
• API.md and CLI.md: the references
• DEVELOPMENT.md: working on the code
• ../AGENTS.md: the runbook for maintainers and AI assistants