Remotehost Docs
API ReferenceAgent sessions

Release a session to its native terminal

POST
/agent-sessions/{sessionId}/release

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.

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

sessionId*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/agent-sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/release"
{  "id": "string",  "sessionId": "string",  "projectId": "string",  "sandboxId": "string",  "agent": "string",  "agentLabel": "string",  "communication": {    "status": "ready",    "capabilities": [      "messages"    ],    "message": "string",    "requirements": [      {        "code": "string",        "action": "restart",        "message": "string"      }    ]  },  "requirements": [    {      "code": "string",      "action": "restart",      "message": "string"    }  ],  "surface": "terminal",  "status": "active",  "turnId": "string",  "turnState": "submitted",  "needsYou": true,  "waitingOn": "string",  "pendingInput": {    "requestId": "string",    "kind": "string",    "summary": "string"  },  "error": "string",  "bridgeState": "starting",  "released": true,  "releasing": true,  "bridgeEventSeq": 0,  "drifted": true,  "problems": [    {      "seq": 0,      "event": "string",      "reason": "string"    }  ],  "resume": {    "command": "string",    "args": [      "string"    ],    "cwd": "string"  }}

Read live sandbox resource metrics GET

Previous Page

Discover agent sessions GET

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.