Skip to content
alfe.aiDocs

Remote sessions

These methods let an agent ask a person to complete a step in its shared browser. See Remote browser and terminal for how takeover looks to the person.

Agents on OpenClaw, Claude Code, and Codex get the takeover flow as the request_browser_takeover tool, which also waits for the hand-back. Calling these methods yourself creates and tracks the session, but it doesn’t hold the browser for the person. All examples use the @alfe.ai/agent-api-client.

Request a takeover

Section titled “Request a takeover”
remote.ts
const { sessionId, status } = await client.requestBrowserTakeover({
  instructions: "Sign in to the supplier portal, then hand back.",
  url: "https://portal.example.com/login", // optional, shown for context only
  conversationId,                          // optional, shows a card in that chat
});
// POST /agent/remote/takeover

instructions can be up to 2,000 characters. Navigate the browser yourself first, because url is only context for the person. Alfe notifies the user when the session is created.

When a takeover is refused

Section titled “When a takeover is refused”

The request needs a live shared browser. Neither refusal creates a session or sends a notification.

code Status Meaning
browser_surface_unavailable 409 The agent has no shared browser connected. Retrying won’t help, so ask the person to do the step themselves.
browser_presence_unavailable 503 Alfe couldn’t confirm the browser is connected. Retry shortly.

Read a session

Section titled “Read a session”
const session = await client.getRemoteSession(sessionId);
// GET /agent/remote/sessions/{sessionId}

status is one of agent_driving, awaiting_human, human_in_control, resuming, completed, expired, or failed.

Complete a session

Section titled “Complete a session”
await client.completeRemoteSession(sessionId);
// POST /agent/remote/sessions/{sessionId}/complete

Read the web terminal setting

Section titled “Read the web terminal setting”

Returns whether the person who manages the agent has left its web terminal on.

const { webTerminalEnabled } = await client.getRemoteSettings();
// GET /agent/remote/settings

An agent can read this setting but can’t change it.

Section titled “Related resources”