Setup The Agent¶

1. Start The Backend¶

From the repository root:

make backend-dev

The backend exposes the generated installer at /api/agents/install.sh.

2. Create An Agent Token¶

You can create the agent from the UI in Settings -> Agents, or directly through the API:

curl -s http://127.0.0.1:8000/api/agents \
  -H 'Content-Type: application/json' \
  -d '{"name":"mac-mini-01"}'

The response includes the agent record and its token.

3. Run The Installer On The Host¶

Use the generated token with the backend installer. For iOS, prefix it with VPHONE_CLI_ROOT pointing at your built vphone-cli checkout (see step 4):

VPHONE_CLI_ROOT=/path/to/vphone-cli \
curl -fsSL http://127.0.0.1:8000/api/agents/install.sh | \
  bash -s -- \
  --backend-url http://127.0.0.1:8000/api \
  --agent-token <token-from-api-or-ui> \
  --agent-host <dns-name-or-ip-reachable-by-backend-and-browser>

For Android-only agents, omit VPHONE_CLI_ROOT.

4. Meet The Platform Prerequisites¶

iOS: Apple Silicon Mac with a built vphone-cli checkout pointed to by VPHONE_CLI_ROOT
Android: Android SDK, JDK, emulator, adb, avdmanager, and ANDROID_SDK_ROOT

There is one supported way to provide vphone-cli: point VPHONE_CLI_ROOT at a built vphone-cli checkout. The installer and the agent derive the binary from .build/ inside it, and the VM-build scripts live there too.

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli
cd vphone-cli && swift build -c release
# then run the installer with VPHONE_CLI_ROOT="$PWD" (see step 3)

Tip

VPHONE_CLI_ROOT is recorded in agent.env, so the running agent never depends on your shell’s PATH. This avoids the common gotcha where vphone-cli works in your terminal but the installer — piped into bash or run under sudo — sees a different, minimal PATH.

The installer prepares the runtime layout under $HOME/.open-device-cloud.

5. Verify Registration¶

List registered agents:

curl -s http://127.0.0.1:8000/api/agents

Look for:

connection_status: "online"
capability details for the platform you enabled
a recent last_seen_at timestamp

Tip

Choose an agent-host value that both the backend and the browser can reach. This matters for screen streaming and browser-side control flows.