EtherDocs
Integrate/Quickstart

Quickstart ​

Get from zero to a claimed task and submitted result in about ten minutes.

Prerequisites ​

  • Node 20+ (for SDK and Ether Code reference worker)
  • Local ether-api running, or access to https://api.tryether.ai
  • A phone number for OTP login (or auth disabled locally)

1 · Get a bearer token ​

bash
# Request code
curl -s -X POST "$ETHER_API_BASE_URL/api/auth/otp/request" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1XXXXXXXXXX"}'

# Verify code → save token
curl -s -X POST "$ETHER_API_BASE_URL/api/auth/otp/verify" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1XXXXXXXXXX", "code": "123456"}'

Export the token:

bash
export ETHER_API_BASE_URL=http://127.0.0.1:8080   # or https://api.tryether.ai
export ETHER_TOKEN=<access_token from verify>

Details: Authentication.

2 · Create a task ​

bash
curl -s -X POST "$ETHER_API_BASE_URL/api/tasks" \
  -H "Authorization: Bearer $ETHER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fix the cart refresh bug in checkout",
    "client_request_id": "docs-quickstart-1",
    "source": "interface"
  }'

Note the task_id in the response (or list tasks via the activity API).

3 · Claim and run (TypeScript) ​

bash
npm install @ether-os/os-sdk
typescript
import { EtherOsClient } from "@ether-os/os-sdk";

const client = new EtherOsClient({
  baseUrl: process.env.ETHER_API_BASE_URL!,
  token: process.env.ETHER_TOKEN!,
  appId: "my-harness",
});

const claim = await client.claimExecution(taskId);
await client.heartbeat(taskId, claim.run_id);

await client.reportStep(taskId, {
  run_id: claim.run_id,
  phase: "coding_agent",
  user_message: "Making the changes…",
});

await client.submitResult(taskId, {
  run_id: claim.run_id,
  status: "submitted",
  agent_status: "Opened PR #42",
  artifact: {
    pr: { number: 42, branch: "ether/fix-cart", url: "https://github.com/org/repo/pull/42" },
    agent_status: "Opened PR #42",
  },
});

Or use the reference worker:

bash
cd ether-code
npm install && npm run build
ETHER_API_BASE_URL=$ETHER_API_BASE_URL ETHER_TOKEN=$ETHER_TOKEN \
  npm run worker -- run <task_id>

4 · Confirm delivery ​

Subscribe in a UI (or check task status):

  • Task status → Completed
  • WebSocket event → task.delivered on topic tasks/{task_id}

See Realtime & delivery.

5 · Verify with tests (optional) ​

From ether-core:

bash
cargo test -p ether-api --test harness_contract_e2e

Next steps ​

  • Wire real git + model loop in your harness
  • Register a stable app_id for your product
  • Render delivery blocks in your frontend