Remote connections

Your app still runs on your computer or connected device. The hosted connection lets a remote AI client send testing requests and receive screenshots and UI information through Ceraph. Your computer must stay awake and connected while testing.

1. Set up the project locally

Complete the prerequisites and project initialization in the local setup guide, then run ceraph connect --help to check its options. Installing the remote connection in an AI client does not install Ceraph or the platform tools on your computer.

2. Connect your AI client

In your remote MCP client, add the endpoint for your profile and complete Ceraph sign-in and authorization. Use the same Ceraph account for the browser pairing in the next step.

• OpenAI: https://mcp.ceraph.dev/openai/mcp with --profile openai.
• General: https://mcp.ceraph.dev/mcp with --profile general.

Use the profile that matches your client. Adding an endpoint does not grant access to your local app; you approve that separately on your computer.

3. Pair your computer and choose a target

Run one of these commands, replacing the project path and target identifier:

ceraph connect --project-dir <path> --simulator <UDID> --profile openai

ceraph connect --project-dir <path> --emulator <AVD-or-serial> --profile openai

ceraph connect --project-dir <path> --platform <ios|android> --device <ID> --profile openai

Use --profile general instead for the general endpoint. iOS requires macOS; Android works on macOS, Windows, or Linux. Add --headless for an iOS Simulator without its window, or --no-window for an Android emulator without a window.

Follow the browser pairing prompt and check that its code matches your terminal. Return to the terminal to confirm the account, project, and device before access starts. Normal testing uses that approved scope; machine or account changes require additional local approval.

4. Test, disconnect, and reconnect

Keep the terminal running and ask your remote agent to test the app. The connection can last up to eight hours. Press Ctrl+C in the terminal to end access, and run ceraph connect with the same options for another session. Confirm the project and device each time; browser pairing is remembered for up to 30 days of inactivity.

To forget this computer for a profile:

ceraph connect --forget --profile openai

If your client cannot reach the app, check that the terminal connection is still running, the endpoint and profile match, and both use the same account. Reconnect if the session has expired. If the command is missing, update Ceraph. If authorization fails, sign in again with the account used for pairing.