Overview

lexmount:remote exposes an online computer or server to cloud tasks. Files, processes, and network connections operate on the selected client; HTTP server handlers still execute in the cloud JavaScript environment. Start the native client using the quickstart first.

• host.fs: Read and write files, traverse directories, and inspect metadata.
• host.fetch: Request client-local, private-network, or public HTTP services.
• host.process: Query processes and execute or control shell commands.
• host.tcp: Create TCP connections and listeners.
• host.http: Listen on the client and handle HTTP requests in the cloud.

import { getRemoteHosts, remoteHosts } from 'lexmount:remote';

const hosts = await getRemoteHosts();
const info = hosts.find((item) => item.id === '<client-id>');
if (!info) throw new Error('Client is offline or unavailable');
const host = remoteHosts[info.id];
console.log(await host.fs.readTextFile('notes.txt'));

Host discovery

getRemoteHosts()

Function: queries online clients and refreshes remoteHosts.

Parameters: none.

Return value: Promise<RemoteHostInfo[]>. Fields are read-only; unavailable system information is null.

System information is sampled on registration or reconnection. The initial module import can also query hosts and fail. To catch import errors, place await import('lexmount:remote') inside try/catch.

remoteHosts

Function: exposes Readonly<Record<string, RemoteHost>>, mapping client IDs to operation handles. Configured initial import and each getRemoteHosts() call refresh it; it does not update continuously.

Access parameter: the id: string in remoteHosts[id] is the full client ID.

Return value: a RemoteHost, or undefined when absent. Each host exposes read-only id: string, fs, fetch, process, tcp, and http. Operations on existing handles still check the current connection.

Client permissions

Open Configure on Clients, edit the settings, and save. First-connection defaults are:

{
  "fs": { "enabled": true, "allow_write": false },
  "process": { "enabled": true, "allow_exec": true },
  "tcp": { "enabled": true },
  "http_server": { "enabled": true }
}

fs.allow_write=false restricts filesystem API writes; an allowed shell command can still modify files. File reads follow the client's system user permissions, without an additional path allowlist.

Configuration is saved per user and client ID, rather than per project. Offline saves synchronize on reconnection; use the client-confirmed version to determine application. New configuration affects subsequent operations; existing operations continue, and closing and cleanup remain allowed.

Errors and resource release

Remote failures are Error objects with name and code, such as RemoteFsError, RemoteFetchError, RemoteProcessError, RemoteTcpError, RemoteHttpError, and registry RemoteError. Those names are not exported constructors. Branch on error.code, such as host_disconnected, permission_denied, or remote_unavailable. Invalid arguments can also throw TypeError.

Host discovery rejects with remote_unavailable when the remote capability is unconfigured. Offline clients, permission changes, and network failures can also fail calls. Reconnection does not automatically replay application operations.

Directory iterators, process snapshots, and unconsumed responses do not independently keep a task active. Running children, TCP connections and listeners, and HTTP servers do. Consume and explicitly close resources; the runtime also cleans up when the task ends or stops.

See the remote examples and remote.d.ts.