Remotehost Docs
API ReferenceAgent sessions

Discover agent sessions

GET
/agent-sessions

Discover registered sessions across accessible projects. Organization API keys retain their org limit; personal agent tokens span accessible orgs. New Codex terminals are registered; existing standalone and native Claude sessions are not attached. State is last known; read a session to refresh it. Pages are ordered by stable session ID, not activity.

Authorization

bearerAuth
AuthorizationBearer <token>

A RemoteHost API key (rh_sk_...) or a user session token.

In: header

Query Parameters

orgId?string
Formatuuid
projectId?string
Formatuuid
sandboxId?string
Formatuuid
after?string
Formatuuid
limit?integer
Range1 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/agent-sessions"
{  "sessions": [    {      "id": "string",      "org_id": "string",      "project_id": "string",      "sandbox_id": "string",      "agent": "string",      "agent_label": "string",      "status": "active",      "last_activity_at": "string",      "surface": "terminal",      "sandbox_status": "string",      "turn_id": "string",      "turn_state": "submitted",      "needs_you": true,      "permissions": [        "agent_session.read"      ]    }  ],  "nextCursor": "string",  "hasMore": true}

Release a session to its native terminal POST

Release an idle managed session to its native terminal without deleting its saved conversation. Requires agent_session.send and bridge v8. Refuses active turns; interrupt first. Returns resume arguments only after the bridge and agent processes exit. Retry on an uncertain response; repeated release is safe. Close manual CLI ownership before using recover to restore remote control. Native terminal surfaces are unsupported.

Start an agent session POST

Start a separate managed conversation using this running sandbox's configured agent. Does not attach to its native terminal conversation. Requires agent_session.send.