Simulator agent integration

​

Connection contract

npx skills add newly-app/run-cloud-examples --skill run-cloud-ios-simulator

​

Standard Agent2Agent connection

git clone --depth 1 https://github.com/newly-app/run-cloud-examples.git
cd run-cloud-examples/a2a-simulator
npm ci
npm test
npm start

{"operation":"create","platform":"ios","orgId":"your-organization","idempotencyKey":"your-stable-request-id"}

​

Account registration and authentication

1. Sign in or create an account at run.cloud/login. Email sign-in requires access to the verification inbox.
2. Select the organization that will own the sessions and pay for their usage. Check membership before creating resources. If the account has no organization, resolve account setup with support before proceeding.
3. For an SDK integration, create a named API key in the dashboard and store it in your platform’s secret store as RUN_CLOUD_API_KEY. Never put it in a prompt, URL, or source file.
4. For CLI use, sign in once or inject that API key into the tool’s environment.

npm install -g runcloud
runcloud login --email [email protected]
runcloud account --json

​

Billing and payment authorization

​

Runnable simulator workflow

npm install @run-cloud/sdk

• RUN_CLOUD_API_KEY: the customer’s secret API key.
• RUN_CLOUD_ORG_ID: the organization selected from the account’s memberships.
• RUN_CLOUD_REQUEST_ID: a unique ID for this allocation. Preserve it when retrying a request whose response was lost; use a new ID for a new allocation.
• SIMULATOR_PLATFORM: ios (default) or android.

import { writeFile } from "node:fs/promises";
import { Client } from "@run-cloud/sdk";

const apiKey = process.env.RUN_CLOUD_API_KEY;
const orgId = process.env.RUN_CLOUD_ORG_ID;
const requestId = process.env.RUN_CLOUD_REQUEST_ID;
const platform = process.env.SIMULATOR_PLATFORM ?? "ios";
if (!apiKey || !orgId || !requestId) {
  throw new Error("API key, organization ID, and request ID are required");
}
if (platform !== "ios" && platform !== "android") {
  throw new Error("SIMULATOR_PLATFORM must be ios or android");
}

const cloud = new Client({ apiKey });
const credential = await cloud.credential();
if (!credential.runCloud || !credential.orgs.includes(orgId)) {
  throw new Error("The credential does not authorize this organization");
}
await cloud.account();
const usageBefore = await cloud.usage({ orgId });
const mobile = platform === "ios" ? cloud.ios : cloud.android;
const session = await mobile.create({
  orgId,
  idempotencyKey: requestId,
  displayName: "Agent simulator review",
  inactivityTimeout: "60s",
  hardTimeout: "5m",
});

try {
  await mobile.openUrl(session.id, "https://run.cloud");
  await writeFile("before.png", await mobile.screenshot(session.id), { mode: 0o600 });
  const acknowledgement = await mobile.pressButton(session.id, "home");
  await writeFile("after.png", await mobile.screenshot(session.id), { mode: 0o600 });
  console.log({ sessionId: session.id, actionStatus: acknowledgement.status });
} finally {
  await mobile.delete(session.id);
}

const released = await mobile.get(session.id);
const usageAfter = await cloud.usage({ orgId });
console.log({ sessionId: session.id, status: released.status, usageBefore, usageAfter });

​

Map requests to tools

​

Suggested review prompts

1. “Connect my run.cloud account and check which organization I can use. Keep my API key private.”
2. “Start an iOS simulator on run.cloud with a five-minute maximum lifetime. Give me its session ID and privately share its viewer link.”
3. “Open https://run.cloud on that simulator and show me a screenshot.”
4. “Press Home on the simulator and show me the resulting screen.”
5. “End my simulator session, confirm it was released, and report recorded usage separately from payment status.”

​

Review checklist

• Missing or invalid credentials cannot create or control a session.
• The authenticated user belongs to the selected organization.
• Allocation retries use the same idempotency key; unrelated requests do not.
• The session becomes usable and screenshots confirm the requested interactions.
• The session is released on success and on failure, with an inactivity timeout and a hard lifetime limit as backstops.
• Keys, verification codes, signed URLs, and private screen contents stay out of public transcripts.
• A paid-flow claim includes confirmed account funding and recorded simulator usage; neither successful login nor a generated checkout link is sufficient.