> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsim.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Run a free console test, then connect AgentSIM to an app you own.
Start with a free test in the console. You'll see AgentSIM receive and extract a sample code. Then connect your agent through MCP or an SDK, where an app you own sends the real SMS. Live SMS requires upfront payment: review the [price, allowance, and renewal terms](https://console.agentsim.dev/billing) before opening a live session.
Using Codex, Claude, Cursor, Windsurf, Playwright, or an agent framework? Start with [Integrations](/integrations/overview). MCP users do not need an SDK.
Running the API locally without `GATHER_API_KEY` uses the \$0 mock provider. Open a challenge, [inject an inbound message](/api-reference/inject-otp), then wait for the verdict and release.
## Run a free test
Create an account at [console.agentsim.dev](https://console.agentsim.dev/sign-up). If you sign up with email and password, open the verification link in your inbox, then sign in.
In [Test](https://console.agentsim.dev/dashboard/playground?welcome=1):
1. Select **Start test** to create a test run.
2. Select **Generate test code**.
3. Look for **Code received** and the extracted code in **Result**.
4. Select **View run details** to see the record. You can also find it in **Runs**.
This test uses a sample message. It sends no live SMS, costs nothing, and does not use your paid live allowance. A successful test shows that AgentSIM can receive, extract, and record a code. It does not verify your app's SMS delivery or connect an agent yet.
## Connect your agent
Using Codex CLI? Follow [Connect with Codex](/mcp/connect#codex-cli), then run the [complete phone sign-in workflow](/mcp/recipes#complete-a-phone-sign-in). You do not need to install an AgentSIM SDK for this path.
For code that calls AgentSIM directly, continue with the SDK setup below.
## Get your API key for the live SDK
1. Sign in at [console.agentsim.dev](https://console.agentsim.dev)
2. Open **Keys**, then **Create key** (or use a key you've already saved)
3. Copy the key (starts with `asm_live_`)
Set it as an environment variable:
```bash theme={"dark"}
export AGENTSIM_API_KEY="asm_live_..."
```
## Install the SDK
The live SDK uses TypeScript `openChallenge` / `waitForVerdict`. Those names open an SMS challenge and wait for a verdict. `provision` / `waitForOtp` remain aliases. Python uses `agentsim.open_challenge` / `wait_for_verdict` against the same REST endpoints (`provision` / `wait_for_otp` are aliases).
```bash TypeScript theme={"dark"}
bun add @agentsim/sdk
# or: npm install @agentsim/sdk
```
```bash Python theme={"dark"}
uv add agentsim-sdk
# or: pip install agentsim-sdk
```
## Open a challenge and wait for the verdict
Use this on staging or production auth you own. Do not point it at Google or Stripe.
Complete payment in [Billing](https://console.agentsim.dev/billing) first. Each successful number assignment or extension uses one session, even if no code arrives. Failed assignments use none. Expired or exhausted allowances cannot open another live session; there are no overage charges.
Replace `staging.example.com` below with your real public HTTPS origin. Placeholder, private, reserved, and unresolved targets fail closed before allocation.
This is the live path, not a self-contained demo. `openChallenge` opens live SMS on a Gather Agent Line. Enter the challenge number on an app you own and trigger that app to send the OTP. If no SMS arrives, `waitForVerdict` times out; a timeout proves neither delivery nor OTP success.
```typescript TypeScript theme={"dark"}
import { openChallenge } from "@agentsim/sdk";
// await using releases the session automatically (TypeScript 5.2+)
await using num = await openChallenge({ agentId: "checkout-bot", serviceUrl: "https://staging.example.com" });
console.log("Challenge identifier:", num.number);
// Enter num.number on the owned auth wall...
const otp = await num.waitForVerdict({ timeout: 60 });
console.log("Verdict code:", otp.otpCode);
```
```python Python theme={"dark"}
import agentsim
import os
agentsim.configure(api_key=os.environ["AGENTSIM_API_KEY"])
async with agentsim.open_challenge(agent_id="checkout-bot", service_url="https://staging.example.com") as num:
print(f"Challenge identifier: {num.number}")
# Enter num.number on the owned auth wall...
otp = await num.wait_for_verdict(timeout=60)
print(f"Verdict code: {otp.otp_code}")
```
There is no `AgentSIM()` class. MCP agents should call `open_challenge` then `wait_for_verdict`. `provision_number` and `wait_for_otp` remain MCP aliases.
## How the live SDK path works
AgentSIM is a control plane, not a phone shop. One session is one challenge, one policy check, one verdict.
1. **Open** — `openChallenge()` / `open_challenge` (SDK) or `open_challenge` (MCP) calls `POST /v1/sessions`.
2. **Trigger** — your agent hits the wall on an app you own.
3. **Wait** — `waitForVerdict()` / `wait_for_verdict` calls `POST /v1/sessions/:id/wait`. Timeouts are seconds.
4. **Release** — the session closes; SDKs do this on context exit.
SMS is connector 0. Email, magic links, and passkeys are more walls. Google and Stripe stay denylisted.
Choose MCP, SDK, browser automation, controlled auth, or Agent Skills.
Challenge, policy, and verdict — plus the shipped SDK and MCP names.
Check empirical support before depending on a target service.
REST endpoints that the SDK and MCP call.