agent-device-proxy

Reusable macOS sidecar for remote mobile QA.

It has two jobs:

• expose a host-local HTTP bridge to a macOS agent-device HTTP daemon
• expose a host-local HTTP Metro bridge for simulator/emulator app traffic

Why

The QA worker and Metro run in a Linux sandbox, while the iOS simulator, Android emulator, and agent-device run on a macOS host. agent-device-proxy bridges those two environments so the worker can talk to the host daemon and the app can use a normal host-local Metro endpoint.

Install

npm install -g agent-device-proxy

Run

Start the proxy against an already-running agent-device HTTP daemon:

export AGENT_DEVICE_PROXY_BEARER_TOKEN='<strong-token>' # openssl rand -hex 32
agent-device-proxy serve

For serve, set:

• AGENT_DEVICE_PROXY_BEARER_TOKEN (e.g. generated with openssl rand -hex 32)
• a readable ~/.agent-device/daemon.json (set by agent-device) or AGENT_DEVICE_STATE_DIR

If you want the package to prepare the local agent-device HTTP daemon first, use the helper command instead:

export AGENT_DEVICE_PROXY_BEARER_TOKEN='<strong-token>'
agent-device-proxy dev

dev is macOS-host oriented. It expects:

• agent-device to be installed locally and runnable
• standard host utilities such as ps and lsof
• AGENT_DEVICE_PROXY_BEARER_TOKEN to already be set

If you want a host-side env template, use .env.example.

The package also exposes the macOS bootstrap helper as:

agent-device-proxy-macos-remote-setup --help

Programmatic Usage

Node client:

import { createAgentDeviceProxyClient } from "agent-device-proxy"

const client = createAgentDeviceProxyClient({
  baseUrl: "http://<mac-host>:9124",
  bearerToken: process.env.AGENT_DEVICE_PROXY_BEARER_TOKEN,
})

Embedded server:

import { startAgentDeviceProxyServer } from "agent-device-proxy/server"

startAgentDeviceProxyServer()

More Details

See ARCHITECTURE.md for:

• system architecture and runtime model
• QA flow in this repo
• worker-side env wiring
• Metro endpoint behavior
• operational notes and troubleshooting