GridFleet Agent
gridfleet-agent is the host-side service that registers a device host with a GridFleet manager and spawns Appium per device. WebDriver sessions are routed to the device's Appium process by the GridFleet router (on the manager side); the agent itself runs no Grid relay node.
The agent installs entirely under the operator's home directory — no sudo is required to install, start, update, or uninstall.
Contents
- Quick install
- Prerequisites
- Manual install
- Headless Linux: enable linger
- Commands
- Configuration reference
- Logs and service control
- Troubleshooting
- Security note
Quick install
Both Linux and macOS use the same bootstrap script. It installs uv if missing, creates a dedicated venv under the per-OS user-scope agent directory, installs gridfleet-agent into it, and runs gridfleet-agent install --start — all as the invoking operator, no sudo.
# Latest version (development hosts)
curl -LsSf https://raw.githubusercontent.com/quidow/gridfleet/main/scripts/install-agent.sh \
| sh -s -- --start --manager-url http://manager.example.com:8000
# Production: always pin VERSION
curl -LsSf https://raw.githubusercontent.com/quidow/gridfleet/main/scripts/install-agent.sh \
| VERSION=0.10.0 sh -s -- --start --manager-url http://manager.example.com:8000
The script refuses to run as root. The service runs as the operator that invoked the script.
Prerequisites
The agent itself only needs Python 3.14, which uv fetches automatically. Host-level tools the agent uses — only Node.js is probed during install and wired onto the service PATH:
| Tool | Needed for | Detection |
|---|---|---|
| Node.js 20+ | Per-pack Appium runtimes | nvm (NVM_BIN, ~/.nvm), fnm (FNM_DIR, fnm default), then $PATH |
Java is not probed at install time. It is resolved when Appium launches, in this order: java on $PATH, JAVA_HOME, /usr/libexec/java_home (macOS), then ~/.sdkman/candidates/java. Android tooling (ADB, platform-tools) is provided by the per-pack runtime and adapter, not by the agent installer.
Manual install
# 1. Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
# 2. Create the dedicated venv and install gridfleet-agent.
# Linux:
AGENT_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/gridfleet-agent"
# macOS:
# AGENT_DIR="$HOME/Library/Application Support/gridfleet-agent"
mkdir -p "$AGENT_DIR"
uv venv --python 3.14 "$AGENT_DIR/venv"
uv pip install --python "$AGENT_DIR/venv/bin/python" "gridfleet-agent==0.10.0"
# 3. Provision the service from the dedicated venv. No sudo.
"$AGENT_DIR/venv/bin/gridfleet-agent" install --start --manager-url http://manager.example.com:8000
Headless Linux: enable linger
A systemd user instance runs only while the user has an active login session. For headless lab hosts, enable lingering once per host so the agent survives logout and reboots:
sudo loginctl enable-linger "$USER"
The installer probes this state after systemctl --user enable and prints a warning if linger is off — it does not abort, because desktop / dev hosts where the operator is always logged in do not need it.
Commands
install
Provision files, write the systemd user unit (Linux) or launchd LaunchAgent plist (macOS), optionally start the service. No sudo. Pass exactly one of --dry-run, --no-start, --start.
gridfleet-agent install --dry-run --manager-url http://manager.example.com:8000
gridfleet-agent install --no-start --manager-url http://manager.example.com:8000
gridfleet-agent install --start --manager-url http://manager.example.com:8000
Exit codes: 0 success (including registration pending — printed as a WARNING); 1 files installed but local /agent/health failed; 2 invalid args or setup error.
status
Read-only. Reports config file, service file, service active/enabled, local /agent/health, operator identity, uv path, and the configured environment with secrets redacted.
gridfleet-agent status
update
Drain -> upgrade the dedicated venv in place -> restart -> re-poll health. No sudo.
gridfleet-agent update --to 0.10.0
gridfleet-agent update --dry-run
gridfleet-agent update --uv-bin /path/to/uv # advanced
Exit codes: 0 success; 1 drain timeout, no usable uv binary found, or post-restart health failure; 2 the upgrade command or restart command failed.
uninstall
gridfleet-agent uninstall --yes
gridfleet-agent uninstall --yes --keep-config # leave config dir in place
gridfleet-agent uninstall --yes --keep-agent-dir # leave agent dir in place
Service internals: serve
gridfleet-agent serve is the entrypoint that systemd / launchd invoke; you should not run it by hand.
--version
gridfleet-agent --version
Configuration reference
All flags below belong to install. status, update, and uninstall accept their own subset (update adds --to, --dry-run, --uv-bin).
| Flag | Default | Mapped env var | Notes |
|---|---|---|---|
--manager-url |
http://localhost:8000 |
AGENT_MANAGER_URL |
Manager base URL. |
--port |
5100 |
AGENT_AGENT_PORT |
Agent HTTP port. |
--advertise-ip |
auto-detect | AGENT_ADVERTISE_IP |
Hostname or IP the agent advertises to the manager. Set to host.docker.internal when the manager runs in Docker on the same host. |
--manager-auth-username |
none | AGENT_MANAGER_AUTH_USERNAME |
Required pair with --manager-auth-password. |
--manager-auth-password |
none | AGENT_MANAGER_AUTH_PASSWORD |
Required pair with --manager-auth-username. |
--api-auth-username |
none | AGENT_API_AUTH_USERNAME |
Required pair with --api-auth-password. |
--api-auth-password |
none | AGENT_API_AUTH_PASSWORD |
Required pair with --api-auth-username. |
Install paths (defaults; override with --agent-dir, --config-dir):
| OS | agent_dir |
config_dir |
Service file | Logs |
|---|---|---|---|---|
| Linux | ${XDG_DATA_HOME:-~/.local/share}/gridfleet-agent |
${XDG_CONFIG_HOME:-~/.config}/gridfleet-agent |
${XDG_CONFIG_HOME:-~/.config}/systemd/user/gridfleet-agent.service |
journald (user instance) |
| macOS | ~/Library/Application Support/gridfleet-agent |
~/Library/Application Support/gridfleet-agent/config |
~/Library/LaunchAgents/com.gridfleet.agent.plist |
~/Library/Logs/gridfleet-agent/{stdout,stderr}.log |
install also creates a ~/.local/bin/gridfleet-agent symlink pointing at the dedicated venv so gridfleet-agent status / update / uninstall work without typing the full venv path. Add ~/.local/bin to your PATH if it is not there already (export PATH="$HOME/.local/bin:$PATH"). If a non-symlink file already exists at that path the installer leaves it untouched and prints a warning. uninstall removes the symlink only when it still points into the agent's agent_dir.
Logs and service control
Linux
journalctl --user -u gridfleet-agent -f
systemctl --user status gridfleet-agent
systemctl --user restart gridfleet-agent
macOS
tail -f ~/Library/Logs/gridfleet-agent/stdout.log
tail -f ~/Library/Logs/gridfleet-agent/stderr.log
launchctl print "gui/$(id -u)/com.gridfleet.agent"
launchctl kickstart -k "gui/$(id -u)/com.gridfleet.agent"
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Install ends with WARNING: agent registration pending |
Manager requires manual approval or machine auth | Approve in the manager UI, or pass --manager-auth-username / --manager-auth-password. |
WARNING: user-instance linger is off |
Linux headless host without lingering enabled | sudo loginctl enable-linger "$USER". |
systemctl --user start gridfleet-agent says Failed to connect to bus |
No $XDG_RUNTIME_DIR; SSH session has no D-Bus user session |
Log in via console or loginctl enable-linger so a user systemd instance always runs. |
/agent/health returns 401 |
--api-auth-* mismatch between agent and operator's curl |
Recheck flags; gridfleet-agent status shows the configured username. |
Port 5100 already in use |
Another service bound the agent port | Pick a free port via --port. |
Security note
The quick install pipes a shell script from the main branch — pin VERSION= for production hosts. uv pip install verifies the package wheel against PyPI's hash. Do not run the agent on hosts where uploaded driver-pack adapter wheels are not trusted: those wheels execute in the agent's runtime venv.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gridfleet_agent-0.38.0.tar.gz.
File metadata
- Download URL: gridfleet_agent-0.38.0.tar.gz
- Upload date:
- Size: 254.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fd68a132ebe886eb4e4d50aedf5ad915630eecbf27b8367a32201168bcad3ac8
|
|
| MD5 |
6698b75fc00f1c5537659e8394bef20f
|
|
| BLAKE2b-256 |
27f3ee344cb69a3b81262d15032fa5c22d41972b6404db558ba83da768ab3aab
|
Provenance
The following attestation bundles were made for gridfleet_agent-0.38.0.tar.gz:
Publisher:
release-please.yml on quidow/gridfleet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gridfleet_agent-0.38.0.tar.gz -
Subject digest:
fd68a132ebe886eb4e4d50aedf5ad915630eecbf27b8367a32201168bcad3ac8 - Sigstore transparency entry: 2194690935
- Sigstore integration time:
-
Permalink:
quidow/gridfleet@397e7ea35ed7f49c07b86895dbb748f3a30a869b -
Branch / Tag:
refs/heads/main - Owner: https://github.com/quidow
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-please.yml@397e7ea35ed7f49c07b86895dbb748f3a30a869b -
Trigger Event:
push
-
Statement type:
File details
Details for the file gridfleet_agent-0.38.0-py3-none-any.whl.
File metadata
- Download URL: gridfleet_agent-0.38.0-py3-none-any.whl
- Upload date:
- Size: 115.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e9a371c02a4c8ac9b1c6616be9897154fb4807bcb5caffdb3fde304323acc918
|
|
| MD5 |
b499c9e9f644215a99dba65971b33784
|
|
| BLAKE2b-256 |
5816e9fbdb6a9db52d7b9a5d96e12c1d80b834d74d6f3c98143b0c19232d6f19
|
Provenance
The following attestation bundles were made for gridfleet_agent-0.38.0-py3-none-any.whl:
Publisher:
release-please.yml on quidow/gridfleet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
gridfleet_agent-0.38.0-py3-none-any.whl -
Subject digest:
e9a371c02a4c8ac9b1c6616be9897154fb4807bcb5caffdb3fde304323acc918 - Sigstore transparency entry: 2194690941
- Sigstore integration time:
-
Permalink:
quidow/gridfleet@397e7ea35ed7f49c07b86895dbb748f3a30a869b -
Branch / Tag:
refs/heads/main - Owner: https://github.com/quidow
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-please.yml@397e7ea35ed7f49c07b86895dbb748f3a30a869b -
Trigger Event:
push
-
Statement type:
