UncageClient
View as MarkdownDefined in: client/src/client.ts:80
Methods
Section titled “Methods”attachmentUrl()
Section titled “attachmentUrl()”attachmentUrl(attachmentId): string;Defined in: client/src/client.ts:94
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
attachmentId |
string |
Returns
Section titled “Returns”string
cancelRun()
Section titled “cancelRun()”cancelRun(runId): Promise<{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "auth_required" | "runtime_unavailable" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; }; id: string; prompt: string; sessionId: string; startedAt?: string; state: | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted";}>;Defined in: client/src/client.ts:87
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
runId |
string |
Returns
Section titled “Returns”Promise<{
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "auth_required"
| "runtime_unavailable"
| "unsupported_capability"
| "invalid_workspace"
| "session_busy"
| "session_read_only"
| "not_found"
| "unauthorized"
| "forbidden_origin"
| "invalid_request"
| "approval_expired"
| "approval_already_resolved"
| "event_replay_unavailable"
| "runtime_disconnected"
| "policy_denied"
| "store_locked"
| "attachment_too_large"
| "attachment_type_unsupported"
| "machine_offline"
| "machine_not_found"
| "upgrade_required"
| "tool_failed"
| "device_code_expired"
| "rate_limited"
| "internal_error";
details?: Record<string, unknown>;
hint?: string;
message: string;
requestId?: string;
retryable: boolean;
};
id: string;
prompt: string;
sessionId: string;
startedAt?: string;
state: | "queued"
| "running"
| "waiting_approval"
| "completed"
| "failed"
| "cancelled"
| "interrupted";
}>
createSession()
Section titled “createSession()”createSession(b): Promise<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "shell" | "network" | "other")[]; }; attachments: { files: boolean; images: boolean; maxBytes: number; maxImageBytes?: number; }; diffEvents: boolean; efforts: ("low" | "medium" | "high" | "xhigh" | "max")[]; mcp: boolean; models: object[]; modelsAuthoritative?: boolean; nativeResume: boolean; permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[]; siteTools: boolean; skills: "unknown" | "supported" | "partial" | "prompt"; streaming: boolean; }; createdAt: string; id: string; machineId?: string; readOnly: boolean; runtimeId: string; settings: { effort?: "low" | "medium" | "high" | "xhigh" | "max"; model?: string; permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions"; }; status: "ready" | "busy" | "unavailable" | "closed"; title: string; workspace: string;}>;Defined in: client/src/client.ts:83
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
b |
CreateSessionRequest |
Returns
Section titled “Returns”Promise<{
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "shell" | "network" | "other")[];
};
attachments: {
files: boolean;
images: boolean;
maxBytes: number;
maxImageBytes?: number;
};
diffEvents: boolean;
efforts: ("low" | "medium" | "high" | "xhigh" | "max")[];
mcp: boolean;
models: object[];
modelsAuthoritative?: boolean;
nativeResume: boolean;
permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[];
siteTools: boolean;
skills: "unknown" | "supported" | "partial" | "prompt";
streaming: boolean;
};
createdAt: string;
id: string;
machineId?: string;
readOnly: boolean;
runtimeId: string;
settings: {
effort?: "low" | "medium" | "high" | "xhigh" | "max";
model?: string;
permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
};
status: "ready" | "busy" | "unavailable" | "closed";
title: string;
workspace: string;
}>
decide()
Section titled “decide()”decide( approvalId, d, idempotencyKey?): Promise<{ allowedScopes: ("once" | "session")[]; availableDecisions: ("deny" | "allow_once" | "allow_session")[]; category: "mcp" | "file" | "shell" | "network" | "other"; createdAt: string; decision?: "deny" | "allow"; description?: string; expiresAt: string; id: string; runId: string; runtimeId: string; sessionId: string; state: | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling"; target: { command?: string; cwd?: string; host?: string; path?: string; }; title: string; toolId?: string; version: number;}>;Defined in: client/src/client.ts:96
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
approvalId |
string |
d |
{ decision: "deny" | "allow"; reason?: string; scope: "once" | "session"; } |
d.decision |
"deny" | "allow" |
d.reason? |
string |
d.scope |
"once" | "session" |
idempotencyKey? |
string |
Returns
Section titled “Returns”Promise<{
allowedScopes: ("once" | "session")[];
availableDecisions: ("deny" | "allow_once" | "allow_session")[];
category: "mcp" | "file" | "shell" | "network" | "other";
createdAt: string;
decision?: "deny" | "allow";
description?: string;
expiresAt: string;
id: string;
runId: string;
runtimeId: string;
sessionId: string;
state: | "failed"
| "cancelled"
| "pending"
| "submitting"
| "approved"
| "denied"
| "expired"
| "reconciling";
target: {
command?: string;
cwd?: string;
host?: string;
path?: string;
};
title: string;
toolId?: string;
version: number;
}>
decideDevice()
Section titled “decideDevice()”decideDevice(code, approve): Promise<DeviceDecision>;Defined in: client/src/client.ts:121
Connected mode: approves (binds the computer to the signed-in user) or denies a device code.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
code |
string |
approve |
boolean |
Returns
Section titled “Returns”Promise<DeviceDecision>
health()
Section titled “health()”health(): Promise<{ ok: true; protocol: "1.0";}>;Defined in: client/src/client.ts:81
Returns
Section titled “Returns”Promise<{
ok: true;
protocol: "1.0";
}>
installInfo()
Section titled “installInfo()”installInfo(): Promise<InstallInfo>;Defined in: client/src/client.ts:115
Connected mode: the install and setup commands for connecting a computer.
Returns
Section titled “Returns”Promise<InstallInfo>
listActiveRuns()
Section titled “listActiveRuns()”listActiveRuns(): Promise<object[]>;Defined in: client/src/client.ts:95
Returns
Section titled “Returns”Promise<object[]>
listSessions()
Section titled “listSessions()”listSessions(): Promise<object[]>;Defined in: client/src/client.ts:84
Returns
Section titled “Returns”Promise<object[]>
lookupDevice()
Section titled “lookupDevice()”lookupDevice(code): Promise<DeviceLookup | null>;Defined in: client/src/client.ts:119
Connected mode: a pending device code for the approve screen, or null if unknown / no longer pending.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
code |
string |
Returns
Section titled “Returns”Promise<DeviceLookup | null>
machines()
Section titled “machines()”machines(): Promise<object[]>;Defined in: client/src/client.ts:113
Connected mode (an Uncage hub): the signed-in user’s computers. A local daemon has no
/machines and rejects with status 404, which is how UIs tell the two modes apart.
Returns
Section titled “Returns”Promise<object[]>
reconnect()
Section titled “reconnect()”reconnect(opts?): void;Defined in: client/src/client.ts:108
Restarts the open subscriptions at once from their last sequence (no duplicates, no gap), skipping any backoff wait. Call it when a mobile app returns to the foreground. No-op when nothing is subscribed.
A stream that is live and received bytes (an event or the server’s heartbeat) within the
last 20 s is kept: it is only restarted if no byte arrives before that window runs out (a
socket that died silently while the app was briefly in the background). { force: true }
restarts every stream regardless.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
opts? |
{ force?: boolean; } |
opts.force? |
boolean |
Returns
Section titled “Returns”void
revokeMachine()
Section titled “revokeMachine()”revokeMachine(machineId): Promise<void>;Defined in: client/src/client.ts:117
Connected mode: disconnects (revokes) one of the user’s computers.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
machineId |
string |
Returns
Section titled “Returns”Promise<void>
runtimes()
Section titled “runtimes()”runtimes(): Promise<object[]>;Defined in: client/src/client.ts:82
Returns
Section titled “Returns”Promise<object[]>
snapshot()
Section titled “snapshot()”snapshot(sessionId): Promise<{ lastSequence: number; pendingApprovals: object[]; runs: object[]; session: { activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "shell" | "network" | "other")[]; }; attachments: { files: boolean; images: boolean; maxBytes: number; maxImageBytes?: number; }; diffEvents: boolean; efforts: ("low" | "medium" | "high" | "xhigh" | "max")[]; mcp: boolean; models: object[]; modelsAuthoritative?: boolean; nativeResume: boolean; permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[]; siteTools: boolean; skills: "unknown" | "supported" | "partial" | "prompt"; streaming: boolean; }; createdAt: string; id: string; machineId?: string; readOnly: boolean; runtimeId: string; settings: { effort?: "low" | "medium" | "high" | "xhigh" | "max"; model?: string; permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions"; }; status: "ready" | "busy" | "unavailable" | "closed"; title: string; workspace: string; };}>;Defined in: client/src/client.ts:85
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
Returns
Section titled “Returns”Promise<{
lastSequence: number;
pendingApprovals: object[];
runs: object[];
session: {
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "shell" | "network" | "other")[];
};
attachments: {
files: boolean;
images: boolean;
maxBytes: number;
maxImageBytes?: number;
};
diffEvents: boolean;
efforts: ("low" | "medium" | "high" | "xhigh" | "max")[];
mcp: boolean;
models: object[];
modelsAuthoritative?: boolean;
nativeResume: boolean;
permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[];
siteTools: boolean;
skills: "unknown" | "supported" | "partial" | "prompt";
streaming: boolean;
};
createdAt: string;
id: string;
machineId?: string;
readOnly: boolean;
runtimeId: string;
settings: {
effort?: "low" | "medium" | "high" | "xhigh" | "max";
model?: string;
permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
};
status: "ready" | "busy" | "unavailable" | "closed";
title: string;
workspace: string;
};
}>
startRun()
Section titled “startRun()”startRun(sessionId, b): Promise<{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "auth_required" | "runtime_unavailable" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; }; id: string; prompt: string; sessionId: string; startedAt?: string; state: | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted";}>;Defined in: client/src/client.ts:86
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
b |
{ attachmentIds?: string[]; prompt: string; } |
b.attachmentIds? |
string[] |
b.prompt |
string |
Returns
Section titled “Returns”Promise<{
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "auth_required"
| "runtime_unavailable"
| "unsupported_capability"
| "invalid_workspace"
| "session_busy"
| "session_read_only"
| "not_found"
| "unauthorized"
| "forbidden_origin"
| "invalid_request"
| "approval_expired"
| "approval_already_resolved"
| "event_replay_unavailable"
| "runtime_disconnected"
| "policy_denied"
| "store_locked"
| "attachment_too_large"
| "attachment_type_unsupported"
| "machine_offline"
| "machine_not_found"
| "upgrade_required"
| "tool_failed"
| "device_code_expired"
| "rate_limited"
| "internal_error";
details?: Record<string, unknown>;
hint?: string;
message: string;
requestId?: string;
retryable: boolean;
};
id: string;
prompt: string;
sessionId: string;
startedAt?: string;
state: | "queued"
| "running"
| "waiting_approval"
| "completed"
| "failed"
| "cancelled"
| "interrupted";
}>
subscribe()
Section titled “subscribe()”subscribe(sessionId, h): () => void;Defined in: client/src/client.ts:97
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
h |
SubscribeHandlers |
Returns
Section titled “Returns”() => void
updateSettings()
Section titled “updateSettings()”updateSettings(sessionId, patch): Promise<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("mcp" | "file" | "shell" | "network" | "other")[]; }; attachments: { files: boolean; images: boolean; maxBytes: number; maxImageBytes?: number; }; diffEvents: boolean; efforts: ("low" | "medium" | "high" | "xhigh" | "max")[]; mcp: boolean; models: object[]; modelsAuthoritative?: boolean; nativeResume: boolean; permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[]; siteTools: boolean; skills: "unknown" | "supported" | "partial" | "prompt"; streaming: boolean; }; createdAt: string; id: string; machineId?: string; readOnly: boolean; runtimeId: string; settings: { effort?: "low" | "medium" | "high" | "xhigh" | "max"; model?: string; permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions"; }; status: "ready" | "busy" | "unavailable" | "closed"; title: string; workspace: string;}>;Defined in: client/src/client.ts:88
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
patch |
Partial<SessionSettings> |
Returns
Section titled “Returns”Promise<{
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("mcp" | "file" | "shell" | "network" | "other")[];
};
attachments: {
files: boolean;
images: boolean;
maxBytes: number;
maxImageBytes?: number;
};
diffEvents: boolean;
efforts: ("low" | "medium" | "high" | "xhigh" | "max")[];
mcp: boolean;
models: object[];
modelsAuthoritative?: boolean;
nativeResume: boolean;
permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[];
siteTools: boolean;
skills: "unknown" | "supported" | "partial" | "prompt";
streaming: boolean;
};
createdAt: string;
id: string;
machineId?: string;
readOnly: boolean;
runtimeId: string;
settings: {
effort?: "low" | "medium" | "high" | "xhigh" | "max";
model?: string;
permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
};
status: "ready" | "busy" | "unavailable" | "closed";
title: string;
workspace: string;
}>
uploadAttachment()
Section titled “uploadAttachment()”uploadAttachment( sessionId, file, opts?): Promise<{ createdAt: string; id: string; kind: "file" | "image"; mime: string; name: string; sessionId: string; sha256: string; size: number;}>;Defined in: client/src/client.ts:93
Uploads a file: a browser File (Blob & { name }) or, in React Native, a picked file
reference { uri, name, type } (read through the runtime’s built-in fetch(uri)).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
file |
RNFile | Blob & object |
opts? |
{ signal?: AbortSignal; } |
opts.signal? |
AbortSignal |
Returns
Section titled “Returns”Promise<{
createdAt: string;
id: string;
kind: "file" | "image";
mime: string;
name: string;
sessionId: string;
sha256: string;
size: number;
}>