# UncageClient

<!-- https://uncage.vercel.app/docs/api/client/interfaces/uncageclient/ -->

Defined in: client/src/client.ts:80

## Methods

### attachmentUrl()

```ts
attachmentUrl(attachmentId): string;
```

Defined in: client/src/client.ts:94

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `attachmentId` | `string` |

#### Returns

`string`

***

### cancelRun()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `runId` | `string` |

#### 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()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `b` | [`CreateSessionRequest`](https://uncage.vercel.app/docs/api/client/type-aliases/createsessionrequest.md) |

#### 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()

```ts
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

| 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

`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()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `code` | `string` |
| `approve` | `boolean` |

#### Returns

`Promise`\<[`DeviceDecision`](https://uncage.vercel.app/docs/api/client/type-aliases/devicedecision.md)\>

***

### health()

```ts
health(): Promise<{
  ok: true;
  protocol: "1.0";
}>;
```

Defined in: client/src/client.ts:81

#### Returns

`Promise`\<\{
  `ok`: `true`;
  `protocol`: `"1.0"`;
\}\>

***

### installInfo()

```ts
installInfo(): Promise<InstallInfo>;
```

Defined in: client/src/client.ts:115

Connected mode: the install and setup commands for connecting a computer.

#### Returns

`Promise`\<[`InstallInfo`](https://uncage.vercel.app/docs/api/client/interfaces/installinfo.md)\>

***

### listActiveRuns()

```ts
listActiveRuns(): Promise<object[]>;
```

Defined in: client/src/client.ts:95

#### Returns

`Promise`\<`object`[]\>

***

### listSessions()

```ts
listSessions(): Promise<object[]>;
```

Defined in: client/src/client.ts:84

#### Returns

`Promise`\<`object`[]\>

***

### lookupDevice()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `code` | `string` |

#### Returns

`Promise`\<[`DeviceLookup`](https://uncage.vercel.app/docs/api/client/interfaces/devicelookup.md) \| `null`\>

***

### machines()

```ts
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

`Promise`\<`object`[]\>

***

### reconnect()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `opts?` | \{ `force?`: `boolean`; \} |
| `opts.force?` | `boolean` |

#### Returns

`void`

***

### revokeMachine()

```ts
revokeMachine(machineId): Promise<void>;
```

Defined in: client/src/client.ts:117

Connected mode: disconnects (revokes) one of the user's computers.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `machineId` | `string` |

#### Returns

`Promise`\<`void`\>

***

### runtimes()

```ts
runtimes(): Promise<object[]>;
```

Defined in: client/src/client.ts:82

#### Returns

`Promise`\<`object`[]\>

***

### snapshot()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |

#### 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()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |
| `b` | \{ `attachmentIds?`: `string`[]; `prompt`: `string`; \} |
| `b.attachmentIds?` | `string`[] |
| `b.prompt` | `string` |

#### 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()

```ts
subscribe(sessionId, h): () => void;
```

Defined in: client/src/client.ts:97

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |
| `h` | [`SubscribeHandlers`](https://uncage.vercel.app/docs/api/client/interfaces/subscribehandlers.md) |

#### Returns

() => `void`

***

### updateSettings()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |
| `patch` | `Partial`\<[`SessionSettings`](https://uncage.vercel.app/docs/api/client/type-aliases/sessionsettings.md)\> |

#### 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()

```ts
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

| Parameter | Type |
| ------ | ------ |
| `sessionId` | `string` |
| `file` | [`RNFile`](https://uncage.vercel.app/docs/api/client/interfaces/rnfile.md) \| `Blob` & `object` |
| `opts?` | \{ `signal?`: `AbortSignal`; \} |
| `opts.signal?` | `AbortSignal` |

#### Returns

`Promise`\<\{
  `createdAt`: `string`;
  `id`: `string`;
  `kind`: `"file"` \| `"image"`;
  `mime`: `string`;
  `name`: `string`;
  `sessionId`: `string`;
  `sha256`: `string`;
  `size`: `number`;
\}\>
