📥 Installation

Get from zero to running automation in 10 minutes. No API keys required for core features.

Prerequisites

Core (Android):

Requirement	Version	How to Check
Python	3.10+	python3 --version
ADB	Any recent	adb --version
Android phone	5.0+ (API 21+)	Physical device or emulator
USB cable	Data-capable	Not a charge-only cable

iOS (optional, macOS only):

Requirement	Version	How to Check
macOS	any recent	required — iOS setup is Mac-only
Xcode	any recent	xcodebuild -version
Node.js	18+	node --version
Appium 2	2.x	appium --version
Appium XCUITest driver	5.x+	appium driver list --installed
iPhone or iOS simulator	iOS 14+	physical device (trusted, Developer Mode on) or xcrun simctl list devices

Install ADB

Ubuntu/Debian:

sudo apt install android-tools-adb

macOS:

brew install android-platform-tools

Windows:

Download from Android SDK Platform-Tools, extract, and add the folder to your PATH.

Verify ADB is installed:

adb --version
# Android Debug Bridge version 1.0.41

Install iOS Support (Mac only, optional)

Skip this section if you’re only driving Android devices.

# 1. Install Appium 2
npm install -g appium

# 2. Install the iOS XCUITest driver
appium driver install xcuitest

# 3. Start Appium in a separate terminal
appium --base-path /
# Default: http://127.0.0.1:4723

For real iPhones, you also need to:

• Trust the Mac from the iPhone (Settings → General → VPN & Device Management)
• Enable Developer Mode (Settings → Privacy & Security → Developer Mode)
• Sign WebDriverAgent with your Apple developer team (open the XCUITest driver’s WDA project in Xcode once, pick a team for WebDriverAgentRunner, run it against your device)

Full walk-through with env vars, multi-device config, smoke tests, and troubleshooting: iOS Setup guide →

Install Ghost in the Droid

git clone https://github.com/ghost-in-the-droid/android-agent.git
cd ghost-in-the-droid

# Install in development mode (recommended)
pip install -e .

# Or install dependencies manually
pip install flask requests pyyaml openai

The -e flag installs in editable mode so changes to the source take effect immediately.

Configuration

Environment Variables

Create a .env file by copying the example:

cp .env.example .env

No API keys are needed for core automation. The following work out of the box:

• ADB device control (tap, swipe, type, screenshots)
• Skill system (load, run, create skills)
• Macro recording and replay
• Dashboard (all 9 tabs)
• Job scheduler
• App Explorer

Optional: AI Features

Add these to .env only if you need AI-powered features. None are required for core automation — pick the brains and gates you actually use.

Cloud brains (pay-per-call)

Variable	Purpose
OPENAI_API_KEY	OpenAI-backed LLM features
ANTHROPIC_API_KEY	Claude API backend
OPENROUTER_API_KEY	OpenRouter (any model behind one key)

Local / self-hosted brains

Variable	Purpose
OLLAMA_BASE_URL	Override the Ollama endpoint (default http://localhost:11434 — only needed for Docker or cross-machine setups)
GITD_VLLM_BASE_URL	Override the vLLM endpoint (defaults to a tunneled phone-through-Mac URL)
vllm_api_key	Set to EMPTY — vLLM doesn’t enforce auth, but the OpenAI client wants a value

On-device brains

No env vars at all — the model files ship with the companion APK and run inside the phone. See On-Device LLM for the model registry.

Feature gates

Variable	Purpose
GITD_ENABLE_IOS=1	Turn on iPhone support (opt-in; default off)
A11Y_DIFF_ENABLED=false	Kill-switch for the accessibility-tree-diff perception aid (default on)
GITD_ADMIN_TOKEN	Required by /api/skills/install — set it before exposing the server beyond localhost

Device defaults

Variable	Purpose
DEFAULT_DEVICE	Pin the primary phone by ADB serial when several are connected
DEFAULT_PROVIDER	Default LLM brain — claude-code (subscription-backed), or Anthropic API / OpenRouter / Ollama / vLLM / on-device

Observability

Variable	Purpose
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY	Opt into Langfuse tracing (cloud or self-hosted)
LANGFUSE_HOST	Point at a self-hosted Langfuse instance

Local SQLite tracing is always on regardless — Langfuse is purely additive. See Tracing.

Optional: Skill Creator LLM Backends

The Skill Creator supports 4 LLM backends. Configure whichever you want to use:

Backend	Config	Default Model
OpenRouter	OPENROUTER_API_KEY env var	anthropic/claude-sonnet-4
Claude API	ANTHROPIC_API_KEY env var	claude-sonnet-4-20250514
Ollama	Auto-detect at localhost:11434	llama3
Claude Code	claude CLI installed	sonnet

Verify Installation

# Start the server
python3 run.py

Open http://localhost:5055 in your browser. You should see the dashboard with 9 tabs.

# Quick Python verification
python3 -c "
from gitd.bots.common.adb import Device
from gitd.skills.tiktok import load
s = load()
print(f'Skill: {s.name} | Actions: {len(s.list_actions())} | Workflows: {len(s.list_workflows())}')
"
# Expected: Skill: tiktok | Actions: 13 | Workflows: 9

Device Selection

If you have multiple phones connected, set the default device:

# List connected devices
adb devices

# Set default via environment variable
export DEVICE=YOUR_DEVICE_SERIAL

# Or pass per-command
DEVICE=YOUR_DEVICE_SERIAL_2 python3 -m pytest tests/ -v

Project Structure

android-agent/
  run.py                          # Entry point (port 5055)
  pyproject.toml                  # Package config
  .env                            # Your API keys (gitignored)
  gitd/               # All application code
    server.py                     # Flask API (113+ routes)
    db.py                         # SQLite ORM (20+ tables)
    bots/common/adb.py            # Device class
    skills/                       # Skill packages
    agent/                        # LLM content planner
    static/dashboard.html         # SPA dashboard
  data/                           # Runtime data
    gitd.db                  # SQLite database
  tests/                          # Pytest suite (19 files)
  config/                         # Credentials (gitignored)

Next Steps

• Connect Your Phone — enable USB debugging and authorize
• Hello World — run your first automation