fix: support explicit remote daemon endpoints (#189)

* fix: support remote daemon base url

* fix: harden remote daemon endpoint handling

* docs: update remote daemon skill guidance

Author: thymikee

README.md

@@ -236,6 +236,8 @@ Flags:
 - `--activity <component>` (Android app launch only; package/Activity or package/.Activity; not for URL opens)
 - `--session <name>`
 - `--state-dir <path>` daemon state directory override (default: `~/.agent-device`)
+- `--daemon-base-url <url>` explicit remote HTTP daemon base URL; skips local daemon discovery/startup
+- `--daemon-auth-token <token>` remote HTTP daemon auth token; sent in both the JSON-RPC request token and HTTP auth headers (`Authorization: Bearer` and `x-agent-device-token`)
 - `--daemon-transport auto|socket|http` daemon client transport preference
 - `--daemon-server-mode socket|http|dual` daemon server mode (`http` and `dual` expose JSON-RPC over HTTP at `/rpc`)
 - `--tenant <id>` tenant identifier used with session isolation
@@ -514,6 +516,8 @@ Environment selectors:
 - `AGENT_DEVICE_IOS_BOOT_TIMEOUT_MS=<ms>` to adjust iOS simulator boot timeout (default: `120000`, minimum: `5000`).
 - `AGENT_DEVICE_DAEMON_TIMEOUT_MS=<ms>` to override daemon request timeout (default `90000`). Increase for slow physical-device setup (for example `120000`).
 - `AGENT_DEVICE_STATE_DIR=<path>` override daemon state directory (metadata, logs, session artifacts).
+- `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]` connect directly to a remote HTTP daemon and skip local daemon metadata/startup.
+- `AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>` auth token for remote HTTP daemon mode; sent in both the JSON-RPC request token and HTTP auth headers (`Authorization: Bearer` and `x-agent-device-token`).
 - `AGENT_DEVICE_DAEMON_SERVER_MODE=socket|http|dual` daemon server mode. `http` and `dual` expose JSON-RPC 2.0 at `POST /rpc` (`GET /health` available for liveness).
 - `AGENT_DEVICE_DAEMON_TRANSPORT=auto|socket|http` client preference when connecting to daemon metadata.
 - `AGENT_DEVICE_HTTP_AUTH_HOOK=<module-path>` optional HTTP auth hook module path for JSON-RPC server mode.

skills/agent-device/SKILL.md

@@ -25,7 +25,7 @@ Use this skill as a router, not a full manual.
 - Normal UI task: `open` -> `snapshot -i` -> `press/fill` -> `diff snapshot -i` -> `close`
 - Debug/crash: `open <app>` -> `logs clear --restart` -> reproduce -> `network dump` -> `logs path` -> targeted `grep`
 - Replay drift: `replay -u <path>` -> verify updated selectors
-- Remote multi-tenant run: allocate lease -> run commands with tenant isolation flags -> heartbeat/release lease
+- Remote multi-tenant run: allocate lease -> point client at remote daemon base URL -> run commands with tenant isolation flags -> heartbeat/release lease
 - Device-scope isolation run: set iOS simulator set / Android allowlist -> run selectors within scope only
 
 ## Canonical Flows
@@ -62,31 +62,40 @@ agent-device replay -u ./session.ad
 ### 4) Remote Tenant Lease Flow (HTTP JSON-RPC)
 
 ```bash
+# Client points directly at the remote daemon HTTP base URL.
+export AGENT_DEVICE_DAEMON_BASE_URL=http://mac-host.example:4310
+export AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>
+
 # Allocate lease
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"runId":"run-123","tenantId":"acme","ttlMs":60000}}'
 
 # Use lease in tenant-isolated command execution
-agent-device --daemon-transport http \
+agent-device \
   --tenant acme \
   --session-isolation tenant \
   --run-id run-123 \
   --lease-id <lease-id> \
   session list --json
 
 # Heartbeat and release
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
 ```
 
+Notes:
+- `AGENT_DEVICE_DAEMON_BASE_URL` makes the CLI skip local daemon discovery/startup and call the remote HTTP daemon directly.
+- `AGENT_DEVICE_DAEMON_AUTH_TOKEN` is sent in both the JSON-RPC request token and HTTP auth headers.
+- In remote daemon mode, `--debug` does not tail a local `daemon.log`; inspect logs on the remote host instead.
+
 ## Command Skeleton (Minimal)
 
 ### Session and navigation
@@ -208,14 +217,15 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Use short lease TTLs and heartbeat only while work is active; release leases immediately after run completion/failure.
 - Env equivalents for scoped runs: `AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET` (compat `IOS_SIMULATOR_DEVICE_SET`) and
   `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` (compat `ANDROID_DEVICE_ALLOWLIST`).
+- For explicit remote client mode, prefer `AGENT_DEVICE_DAEMON_BASE_URL` / `--daemon-base-url` instead of relying on local daemon metadata or loopback-only ports.
 
 ## Security and Trust Notes
 
 - Prefer a preinstalled `agent-device` binary over on-demand package execution.
 - If install is required, pin an exact version (for example: `npx --yes agent-device@<exact-version> --help`).
 - Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
 - Logs/artifacts are written under `~/.agent-device`; replay scripts write to explicit paths you provide.
-- For remote daemon mode, prefer `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` with `AGENT_DEVICE_HTTP_AUTH_HOOK` and tenant-scoped lease admission.
+- For remote daemon mode, prefer `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` on the host plus client-side `AGENT_DEVICE_DAEMON_BASE_URL`, with `AGENT_DEVICE_HTTP_AUTH_HOOK` and tenant-scoped lease admission where needed.
 - Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.
 
 ## Common Mistakes

skills/agent-device/references/remote-tenancy.md

@@ -6,7 +6,12 @@ tenant/run admission control.
 ## Transport prerequisites
 
 - Start daemon in HTTP mode (`AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual`).
-- Use a token from daemon metadata or `Authorization: Bearer <token>`.
+- Point remote clients at the host with `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`
+  or `--daemon-base-url <url>` so the CLI skips local daemon discovery/startup.
+- Use `AGENT_DEVICE_DAEMON_AUTH_TOKEN` / `--daemon-auth-token` when the client should send the
+  shared daemon token automatically.
+- Direct JSON-RPC callers can use a token in params, `Authorization: Bearer <token>`, or
+  `x-agent-device-token`.
 - Prefer an auth hook (`AGENT_DEVICE_HTTP_AUTH_HOOK`) for caller validation and
   tenant injection.
 
@@ -21,7 +26,7 @@ Use `POST /rpc` with JSON-RPC 2.0 methods:
 Example allocate:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"alloc-1","method":"agent_device.lease.allocate","params":{"tenantId":"acme","runId":"run-123","ttlMs":60000}}'
@@ -30,7 +35,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 Example heartbeat:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"hb-1","method":"agent_device.lease.heartbeat","params":{"leaseId":"<lease-id>","ttlMs":60000}}'
@@ -39,7 +44,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 Example release:
 
 ```bash
-curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
+curl -sS "${AGENT_DEVICE_DAEMON_BASE_URL}/rpc" \
   -H "content-type: application/json" \
   -H "Authorization: Bearer <token>" \
   -d '{"jsonrpc":"2.0","id":"rel-1","method":"agent_device.lease.release","params":{"leaseId":"<lease-id>"}}'
@@ -50,7 +55,7 @@ curl -sS http://127.0.0.1:${AGENT_DEVICE_DAEMON_HTTP_PORT}/rpc \
 For tenant-isolated command execution, pass all four flags:
 
 ```bash
-agent-device --daemon-transport http \
+agent-device \
   --tenant acme \
   --session-isolation tenant \
   --run-id run-123 \
@@ -60,6 +65,9 @@ agent-device --daemon-transport http \
 
 Admission checks require tenant/run/lease scope alignment.
 
+The CLI sends `AGENT_DEVICE_DAEMON_AUTH_TOKEN` in both the JSON-RPC request token field and HTTP
+auth headers so existing daemon auth paths continue to work.
+
 ## Failure semantics
 
 - Missing tenant/run/lease fields in tenant isolation mode: `INVALID_ARGS`
@@ -70,6 +78,8 @@ Admission checks require tenant/run/lease scope alignment.
 
 - Keep TTL short and heartbeat only while a run is active.
 - Release lease immediately on run completion/error paths.
+- For remote debug sessions, inspect logs on the remote host; client-side `--debug` no longer tails
+  a local daemon log when `AGENT_DEVICE_DAEMON_BASE_URL` is set.
 - For bounded hosts, configure:
   - `AGENT_DEVICE_MAX_SIMULATOR_LEASES`
   - `AGENT_DEVICE_LEASE_TTL_MS`

src/__tests__/cli-diagnostics.test.ts

@@ -1,7 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { runCli } from '../cli.ts';
 import type { DaemonRequest, DaemonResponse } from '../daemon-client.ts';
+import { resolveDaemonPaths } from '../daemon/config.ts';
 
 class ExitSignal extends Error {
   public readonly code: number;
@@ -76,6 +80,33 @@ test('cli forwards --debug as verbose/debug metadata', async () => {
   assert.equal(typeof result.calls[0]?.meta?.requestId, 'string');
 });
 
+test('cli does not tail local daemon log when remote daemon base URL is set', async () => {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-cli-remote-'));
+  const daemonPaths = resolveDaemonPaths(stateDir);
+  fs.mkdirSync(path.dirname(daemonPaths.logPath), { recursive: true });
+  fs.writeFileSync(daemonPaths.logPath, 'REMOTE_TAIL_SENTINEL\n', 'utf8');
+
+  const previousBaseUrl = process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+  process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'http://remote-mac.example.test:7777/agent-device';
+
+  try {
+    const result = await runCliCapture(['clipboard', 'write', 'hello', '--debug', '--state-dir', stateDir], async () => {
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      return {
+        ok: true,
+        data: { action: 'write' },
+      };
+    });
+    assert.equal(result.code, null);
+    assert.equal(result.stdout.includes('REMOTE_TAIL_SENTINEL'), false);
+    assert.match(result.stdout, /Clipboard updated/);
+  } finally {
+    if (previousBaseUrl === undefined) delete process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+    else process.env.AGENT_DEVICE_DAEMON_BASE_URL = previousBaseUrl;
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
 test('cli returns normalized JSON failures with diagnostics fields', async () => {
   const result = await runCliCapture(['open', 'settings', '--json'], async () => ({
     ok: false,

src/cli.ts

@@ -99,7 +99,10 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
       const daemonFlags = toDaemonFlags(flags);
       const daemonPaths = resolveDaemonPaths(flags.stateDir ?? process.env.AGENT_DEVICE_STATE_DIR);
       const sessionName = flags.session ?? process.env.AGENT_DEVICE_SESSION ?? 'default';
-      const logTailStopper = flags.verbose && !flags.json ? startDaemonLogTail(daemonPaths.logPath) : null;
+      const remoteDaemonBaseUrl = flags.daemonBaseUrl ?? process.env.AGENT_DEVICE_DAEMON_BASE_URL;
+      const logTailStopper = flags.verbose && !flags.json && !remoteDaemonBaseUrl
+        ? startDaemonLogTail(daemonPaths.logPath)
+        : null;
       const sendDaemonRequest = async (payload: { command: string; positionals: string[]; flags?: Record<string, unknown> }) =>
         await deps.sendToDaemon({
           session: sessionName,