What PocketQA puts on your computer
For whoever approves the lab installer: what it installs, what it can do, what leaves the computer, and how to take it off. The parts marked *from SECURITY.md* are that file's own words, each checked by PocketQA's tests before every release.
Check the installer before it runs
The installer and each release are signed with PocketQA's release key, and each one's SHA-256 is published beside it. To check the installer before it runs, in Terminal:
- Download it, its signature and the public key:
curl -fsSL -O https://staging.pocketqa.dev/install.sh -O https://staging.pocketqa.dev/install.sh.sig -O https://staging.pocketqa.dev/release.pub - Check the key is PocketQA's:
openssl pkey -pubin -in release.pub -outform DER | openssl dgst -sha256must end with the fingerprint under "Updates are signed", below. - Check the signature:
openssl dgst -sha256 -verify release.pub -signature install.sh.sig install.shmust sayVerified OK. If it doesn't, don't run it. - Read it if you like, then run it with the code from your install command:
bash install.sh --code ABCD-2345
The checksum alone (curl -fsSL -O https://staging.pocketqa.dev/install.sh.sha256, then shasum -a 256 -c install.sh.sha256, or sha256sum -c on Linux) shows the download arrived whole, not who made it: it comes from the same service.
What it installs, and where
- PocketQA itself:
~/pocketqa(its code) and~/pocketqa-work(its runs, screenshots, log and keys). Nothing outside your home folder, except the optional lid watcher below. - Tools, on a Mac through Homebrew: Node, libimobiledevice (for iPhones), Google Chrome and Android's platform tools (adb). On Linux, through your package manager: the same, without the iPhone tools. ChromeDriver, matched to Chrome, is downloaded over https from Google's Chrome for Testing storage (
storage.googleapis.com/chrome-for-testing-public/), using Chrome for Testing's own list (googlechromelabs.github.io); download redirects and remote list overrides are refused. It is saved into~/pocketqa-work, with no Node, and used only once it says it's the driver for that Chrome. - Background services, as your user, never as root: - Mac:
dev.pocketqa.agent(takes the dashboard's tests) anddev.pocketqa.hub(the Grid, a WebDriver hub on this computer only), in~/Library/LaunchAgents. - Linux:pocketqa-agent.serviceandpocketqa-hub.service, systemd user services. - Only if your team lets a Mac test with its lid shut: a lid watcher,
com.pocketqa.lidwatch, run by macOS for the whole computer (/Library/LaunchDaemons, script in/Library/PocketQA). It keeps the Mac running closed only while it's on its charger and PocketQA says it's testing.
When it asks for the password
The installer asks once, at the start, and keeps it only while it runs. What it's for:
- Mac: installing Homebrew (if it isn't there), letting Safari be driven by tests (
safaridriver --enable), undoing an older always-awake sleep setting if one is set, and the lid watcher if your team chose it. - Linux: installing packages, adding your user to
plugdev(to use an Android phone), undoing masked sleep, andloginctl enable-linger(so it runs with nobody logged in).
Each is optional: skip one and PocketQA says what it can't do without it.
What it can and can't do
It opens your team's sites in browsers on this computer and on the phones plugged into it, and nothing else. It reads no files outside its own folders, runs as a standard user if you install it as one, and takes only tests your team's account sends it, signed with this computer's own key.
In Safari's test sessions only: a small web extension of PocketQA's own (its listeners for a page's script errors, the same ones it reads every page with), loaded into the test's Safari session on that test's site and PocketQA's control page, and taken off when the test ends. It changes nothing on the page, has no permission but scripting, and is loaded for the test session only, never installed in Safari for your own browsing. *From SECURITY.md:* "Safari's load hook."
The password-free lab_fix safari_sessions repair may ask your own Safari to quit if it still holds an old test session, but only after the Mac has been idle for at least five minutes. If idle time is unknown, Safari is left alone. It quits normally: PocketQA never force-ends Safari if a prompt keeps it open, and asks you to finish instead. *From SECURITY.md:* "The lab computer itself."
Phones
Each phone plugged in has a role your team sets in its dialog: someone's personal phone (until your team says otherwise) or a test device. On a personal phone PocketQA changes no settings and never uses the owner's browser: an iPhone tests in Safari's own clean test window, and an Android phone is never tested in its owner's Chrome, since Chrome there can't give a test a separate browser: it's tested in Chrome Beta when that's installed beside it (its own app with its own data, cleared for the test), and otherwise not at all, its result saying how to install Chrome Beta. It's tested only while it's awake and unlocked: never woken. Only on a test device does it keep the phone awake on its charger, set a longer screen timeout, stop it charging at 80% if your team chooses, and clear its browser between tests. *From SECURITY.md:* "Phones: a test device or someone's own."
The network
Outbound only: it opens no port to your network (the Grid listens on this computer alone, with its own token). For an allowlist, it reaches:
- the PocketQA service it's paired with (
staging.pocketqa.dev), over HTTPS; - the sites your team tests;
- at install and update:
raw.githubusercontent.com,formulae.brew.shandghcr.io(Homebrew, Mac),dl.google.com(Chrome, Linux),registry.npmjs.organdstorage.googleapis.com(ChromeDriver); unpkg.com(the browser-support data it uses to predict what a site needs);example.com, from a test device's browser, only when that device can't open PocketQA's own page: to tell a device with no internet from PocketQA being unreachable.
Removing it
Mac, in Terminal:
`` launchctl bootout gui/$(id -u)/dev.pocketqa.agent; launchctl bootout gui/$(id -u)/dev.pocketqa.hub rm -f ~/Library/LaunchAgents/dev.pocketqa.*.plist; rm -rf ~/pocketqa ~/pocketqa-work sudo launchctl bootout system/com.pocketqa.lidwatch 2>/dev/null; sudo rm -rf /Library/LaunchDaemons/com.pocketqa.lidwatch.plist /Library/PocketQA ``
Linux:
`` systemctl --user disable --now pocketqa-agent.service pocketqa-hub.service rm -f ~/.config/systemd/user/pocketqa-*.service; rm -rf ~/pocketqa ~/pocketqa-work ``
Installed before PocketQA's own names (November 2026)? An update moved it to the names above and left a link at each old one; remove those too (a link goes, not what it points at): rm -rf ~/pocket-lab ~/pocket-lab-work. A Mac's lid watcher keeps its older name: sudo launchctl bootout system/com.pocketlab.lidwatch 2>/dev/null; sudo rm -rf /Library/LaunchDaemons/com.pocketlab.lidwatch.plist /Library/PocketLab. Or let PocketQA do all of it: python3 ~/pocketqa/lab/uninstall.py --dry-run lists what goes, under either name, and without --dry-run removes it.
Then remove the computer from your team's dashboard (Labs › the lab › Remove): its key stops working at once. Homebrew and the tools it installed stay; remove them with Homebrew if you want them gone.
From SECURITY.md
What leaves the computer. With each run: which device, passed or failed, page timings, each page's errors and the requests that failed, the last 15 lines of each device's console, and each flow step: its words, whether it passed, and, unless the team switches it off (Settings › Privacy › Send each flow step's screen text), a line of what a tap hit and of what was on the screen after.
Before any of it leaves, addresses lose their query strings, tokens and emails are masked, and what a flow typed is never sent (the step keeps its field).
With the computer's status: its model, its model identifier (which model and year: a Mac's "MacBookPro16,2", a PC's firmware model name; never a serial number), chip, memory and system (macOS), its free disk space, whether it's on its charger and its battery's level (a number), the phones' models and versions, their health (battery, charging, temperature, free memory and storage, hours since restart), what changes how a site looks or runs on them (screen size and refresh rate, text size, display zoom, dark mode, animations, language and region, Low Power Mode, how hot they are, battery health), whether they're on Wi-Fi with its signal and speed, and whether a VPN is on (never the Wi-Fi network's name), its setup checks and the end of its own log; with a run, also the names of what the site is built with (Flutter, React…), never more of the page; no network name, and a phone is told apart by a short id keyed by the lab's own key, never its serial number.
The service also notes which country the computer's network is in, as Cloudflare sees the request (never its address).
No screenshots or page contents: a page that looks different from its last good run is sent as how much of the screen changed and where (top, middle or bottom), worked out on the computer from screenshots that stay there.
Tests started on the computer itself (the local MCP) report the same way, to the team's own dashboard. Tables are capped at 1.8 MB a send; runs older than 90 days are dropped on the computer.
The lab computer itself. Its key is readable by its user alone, and stays so when it's paired again.
Setup never keeps a computer awake always (no sleep 0, disablesleep or masked sleep, which keep a shut or unplugged laptop running, where it can't cool), and undoes an older setup's that did: PocketQA itself holds a computer awake only while it's on its charger and only for testing, or while a test runs, and lets go otherwise.
A Mac the team lets test with its lid shut gets a lid watcher, installed once with the Mac's password as root's own copy: it runs the Mac closed only on its charger, and only while the lab keeps saying so; unplugged, or the lab stopped, it sleeps.
ChromeDriver is downloaded over https only from Google's Chrome for Testing storage, using Chrome for Testing's own list. Download redirects and remote list overrides are refused; versions are checked before they form a path. The driver is used only once it says it's the driver for that Chrome.
The password-free lab_fix safari_sessions repair can ask the person's own Safari to quit when it still holds an old automation session and the Mac has been idle for at least five minutes. If idle time cannot be read, it leaves Safari alone. It asks Safari to quit normally and never force-ends it if a prompt or unsaved work keeps it open; the result asks the person to finish.
A Linux lab (Android phones and Chrome) runs as its user's own systemd service, never as root, through the same signed updater; setup uses sudo only to install packages, undo an older always-awake, join plugdev and keep it running.
Phones between sites. Desktop Chrome gets a fresh profile every session. Only a test device's Chrome on Android is driven (below): ChromeDriver's own documentation says it starts Chrome there with a clear data directory, and the lab also clears cookies, cache and the site's storage before and after every run (web.py --clear). Either way that's the phone's own Chrome, so a personal phone's never is: a personal phone is tested in Chrome Beta (com.chrome.beta) instead, a separate app with its own data, started and cleared the same way. Storage other sites left (a sign-in provider's, say) isn't cleared yet: see Still open.
Phones: a test device or someone's own. Each phone has a role the team sets in its dialog (Labs › the lab › the phone › Status), asked until someone answers; until then it's someone's own (personal).
On a personal phone PocketQA changes no settings: it doesn't keep it awake, lengthen its screen timeout or change its charging, and the end of a run doesn't set any of them back. Its browser is never the owner's.
An iPhone tests in Safari's own automation window, which starts from a clean slate, hides the owner's tabs until it ends and destroys what the test left (Apple's WebDriver).
Chrome on Android can't give a test a separate browser, so a personal Android phone isn't tested in Chrome, by a test or through the Grid. A test runs in Chrome Beta instead, when it's installed beside Chrome: its own app with its own data, cleared for the test, so the owner's Chrome is never started, cleared or sent anything. Only Chrome Beta's version is read (as Chrome's is), the phone is tested only while its owner has it awake and unlocked, and nothing opens on it afterwards.
Someone who uses Chrome Beta as their own browser would lose its data, so the dashboard and the result name the app. Without Chrome Beta it isn't tested, and its result says how to install it. Its screenshots stay in the run's folder on the computer and go with it, and on the service a run's step screenshots go once its results do.
On a test device PocketQA may keep it awake on its charger, set a 30-minute screen timeout, stop it charging at 80% when the team chooses, and clear its browser between tests.
PocketQA never restarts a phone, whichever it is: when Safari on an iPhone stays held by a test session that ending the session and restarting the lab's driver didn't free, the result and lab_doctor say what a person does. Each result says which a phone was. Making a test device personal stops these changes; it doesn't undo settings already made.
Run diagnostics include fixed pipeline statuses, exit codes and exception categories for CSV generation, evidence collection and detail collection. They never include exception text, commands or home-folder paths. They stay with the account's test result, under the same account and support-access controls.
The lab computer's own network. A lab sits on someone's office or home network, and nobody can point it there: not an agent, a script, a teammate or the service itself.
The service refuses a site or one-off address on a private network (192.168.x, 10.x, .local, a bare name…) from every caller until the team approves it (Settings › Privacy).
The computer decides again for itself, and refuses unless the service said it's approved and it's listed on the computer (~/pocketqa-work/allow-hosts); it checks where a public name really leads, refuses a redirect onto its network, opens only http and https with no password and pages that are paths on the site, fails a flow the moment it leaves its site, and pins desktop Chrome to the address it checked (so a name can't change where it leads mid-test).
The same initial-address and redirect checks cover downloaded flow files and build fingerprints, including both approvals for private addresses.
An expect step answers only true or false. Its own localhost (a dev server) is always allowed.
The Grid on a lab computer. The WebDriver hub (lab/hub.py) listens on the computer itself and needs its own token, made at first start and readable only by that user. It refuses anything a web page open on that computer could send it (an Origin header, another Host, a body that isn't JSON), and any capability that names a program, its arguments, an extension, a profile, a browser to attach to or an app to download: a test needs none of them, and each would run code on the computer. Appium’s grouped options are flattened and checked before selecting the device; they cannot override the device the hub selected.
Updates are signed. Each release is signed with an RSA key held only as a GitHub secret (RELEASE_SIGNING_KEY), never on the service. A computer carries the public half (lab/release.pub, from its install or its first update since the key was set) and takes an update only when the signature checks out, the archive's version is the one announced, it's newer than what it has, and every file in it lands inside the lab's own folder. A copy with no key takes no update at all. The installer carries the public key too, and installs (and --updates) only a download signed with it, saying the key's fingerprint as it does: compare it with this one, SHA-256 3566147f8c0dc519… (in full: 3566147f8c0dc5198f7f96dad66c05dd384e29476ac30c8fafa47efd40376729). So whoever changed the service still couldn't push code to computers that are installed, or roll them back to an old release. Packaging refuses to build a release without the key, or one whose signature doesn't match lab/release.pub.
Installs are signed too. The installer the service hands out (/install.sh) is signed with the same release key, as it's served from that address, byte for byte (/install.sh.sig), and its SHA-256 is published beside it (/install.sh.sha256), as each release's are (/pocket-lab.tar.gz.sha256 and .sig). The setup page and the help offer "download, check, then run" next to the one-line command. The installer installs only a release signed with the key it carries; if one isn't, it stops and says nothing was installed. After every deploy, CI checks the live installer and release against their checksums, and the installer's signature against lab/release.pub. The checksum comes from the same service, so it shows the download arrived whole, not who made it; the signature, checked against the fingerprint above, shows who made it (/security/lab says how, step by step: openssl dgst -sha256 -verify release.pub -signature install.sh.sig install.sh says Verified OK).