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.
SidecarEvent
Section titled “SidecarEvent”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.
SidecarStatus
Section titled “SidecarStatus”SidecarStatus.available
Section titled “SidecarStatus.available”Supported hosts: Lite
available: boolean;SidecarStatus.running
Section titled “SidecarStatus.running”Supported hosts: Lite
running: boolean;SidecarStatus.command
Section titled “SidecarStatus.command”Supported hosts: Lite
command: string;SidecarStatus.launch
Section titled “SidecarStatus.launch”Supported hosts: Lite
launch?: SidecarLaunch;Related types: SidecarLaunch.
SidecarLaunch
Section titled “SidecarLaunch”SidecarLaunch.command
Section titled “SidecarLaunch.command”Supported hosts: Lite
command: string;SidecarLaunch.args
Section titled “SidecarLaunch.args”Supported hosts: Lite
args: string[];PluginSidecar
Section titled “PluginSidecar”PluginSidecar.status
Section titled “PluginSidecar.status”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>.
PluginSidecar.start
Section titled “PluginSidecar.start”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>.
PluginSidecar.stop
Section titled “PluginSidecar.stop”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>.
PluginSidecar.send
Section titled “PluginSidecar.send”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>.
PluginSidecar.onEvent
Section titled “PluginSidecar.onEvent”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.