Skip to content

sidecar

Declare a local program and default arguments in manifest.sidecar. API 3.9 supports configurable: true for reviewed startup configuration; API 3.12 supports maxOutputFrameBytes for bounded large responses. Only standalone page and file Views receive this capability. Native programs retain OS permissions outside the JavaScript sandbox. CLI Serve and mobile do not expose native sidecars.

Usage guide: native-processes. API index.

Signatures, parameters and return types are generated from the SDK. Optional members are not available in every host and context.

Source

Supported hosts: Lite

export type SidecarEvent = {
type: "message";
data: BackgroundMessage;
} | {
type: "stderr";
text: string;
} | {
type: "exit";
code: number | null;
signal: string | null;
} | {
type: "error";
message: string;
};

Related types: BackgroundMessage.

Source

Supported hosts: Lite

available: boolean;

Supported hosts: Lite

running: boolean;

Supported hosts: Lite

command: string;

Supported hosts: Lite

launch?: SidecarLaunch;

Related types: SidecarLaunch.

Source

Supported hosts: Lite

command: string;

Supported hosts: Lite

args: string[];

Source

Supported hosts: Lite

Discovery only: available means an executable was found; running means an owned native process exists. Neither implies protocol readiness or a compatible program version. Does not execute, install or prompt.

status(): Promise<SidecarStatus>;

Returns: Promise<SidecarStatus>.

Supported hosts: Lite

Checks persisted approval per Space, package revision and exact program identity including argv; requests review when missing or changed. Installation/enablement may include the concrete default launch. Overrides require configurable: true. An existing different launch must be stopped first. Pending startup expires after five minutes and is cancelled with its initiating View. Closing a started View only detaches it. Success means OS spawn, not protocol readiness.

start(launch?: SidecarLaunch): Promise<void>;
Parameter Type Required
launch SidecarLaunch No

Returns: Promise<void>.

Supported hosts: Lite

Stops the shared owned process tree and awaits exit, affecting every attached View. Stop retains consent; disabling or uninstalling revokes it. Updating the plugin, leaving the Space, closing its owner window or quitting Lite also stops it. Native side effects are not undone.

stop(): Promise<void>;

Returns: Promise<void>.

Supported hosts: Lite

Writes one JSON value followed by LF. Each frame including LF is limited to 1 MiB; queued stdin including the incoming frame is limited to 4 MiB. Completion means stream write completion, not a native protocol response.

send(data: BackgroundMessage): Promise<void>;
Parameter Type Required
data BackgroundMessage Yes

Returns: Promise<void>.

Supported hosts: Lite

Subscribes without starting a process. Returns a disposable observer; closing the View unsubscribes. stdout is LF-delimited JSON (CRLF accepted). Records default to 1 MiB excluding CRLF; API 3.12 permits manifest.sidecar.maxOutputFrameBytes, an integer from 1 to 16777216. The per-second stdout byte limit is max(16 MiB, twice the record limit); stderr over 1 MiB/s is dropped. Malformed or oversized output emits an error and stops the process; preserve that error when exit follows. Unicode line separators are ordinary string content. Reconcile native state after reattaching because events are not replayed.

onEvent(listener: (event: SidecarEvent) => void): Promise<Disposable>;
Parameter Type Required
listener (event: SidecarEvent) => void Yes

Returns: Promise<Disposable>.

Related types: SidecarStatus, SidecarLaunch, BackgroundMessage, SidecarEvent, Disposable.