@tilt-launcher/sidecar

@tilt-launcher/sidecar

Standalone sidecar process + typed client for the Tilt Launcher SDK. Communicates via JSON-RPC 2.0 over stdio — use it from any runtime or language.

Install

bun add @tilt-launcher/sidecar
# or
npm install @tilt-launcher/sidecar

This installs both the tilt-sidecar binary and the typed TypeScript client. The SDK (@tilt-launcher/sdk) is included as a dependency — no need to install it separately.

Quick Start

import { createSidecarClient } from '@tilt-launcher/sidecar';

const sidecar = createSidecarClient();
await sidecar.ready();

// Everything is typed — same API as the SDK
const config = await sidecar.getConfig();
const status = await sidecar.getStatus();

await sidecar.startEnv('my-app');

sidecar.onStatusUpdate((update) => {
  console.log('Status changed:', update);
});

sidecar.onLogDelta((delta) => {
  console.log('New logs:', delta);
});

// Clean up
sidecar.close();

Why use the sidecar instead of the SDK directly?

	SDK	Sidecar
Use when	Your app is Bun/Node and you want direct control	You want a managed subprocess
Process model	In-process	Separate binary
Language	TypeScript only	Any (JSON-RPC over stdio)
Lifecycle	You manage polling and cleanup	Sidecar handles it
Best for	Libraries, tight integration	Apps, CLIs, multi-language

API

createSidecarClient(options?)

Spawns the sidecar and returns a typed client.

const sidecar = createSidecarClient({
  binPath: '/path/to/tilt-sidecar', // optional, auto-detected
  env: { TILT_LAUNCHER_CONFIG: '/custom/config.json' }, // optional
  readyTimeoutMs: 15000, // optional, default 10s
});

Commands

Method	Returns
ready()	Promise<void> — resolves when sidecar is initialized
getConfig()	Promise<Config>
saveConfig(config)	Promise<Result>
getStatus()	Promise<StatusUpdate>
getLogs(envId)	Promise<{ envLogs, resourceLogs }>
startEnv(envId)	Promise<Result>
stopEnv(envId)	Promise<Result>
restartEnv(envId)	Promise<Result>
triggerResource(envId, name)	Promise<Result>
enableResource(envId, name)	Promise<Result>
disableResource(envId, name)	Promise<Result>
discoverResources(input)	Promise<DiscoverResult>
getHomeDir()	Promise<string>
classifyTiltfilePath(path)	Promise<PickedTiltfile>
readDir(dirPath)	Promise<ReadDirResult>
close()	Kills the sidecar process

Events

sidecar.onStatusUpdate((update: StatusUpdate) => { ... });
sidecar.onLogDelta((delta: LogDelta) => { ... });
sidecar.onConfigUpdated((config: Config) => { ... });

Types

All types are re-exported from @tilt-launcher/sdk:

import type { Config, StatusUpdate, LogDelta, ResourceRow } from '@tilt-launcher/sidecar';

Using the binary directly

The sidecar binary can be used from any language via JSON-RPC 2.0 over stdin/stdout:

# Spawn it
./node_modules/.bin/tilt-sidecar

# Send a request (newline-delimited JSON)
{"jsonrpc":"2.0","id":1,"method":"getStatus","params":{}}

# Receive a response
{"jsonrpc":"2.0","id":1,"result":{"envs":{}}}

# Receive push notifications (no id)
{"jsonrpc":"2.0","method":"statusUpdate","params":{...}}

Requirements

• tilt must be on $PATH
• macOS or Linux (no Windows support yet)

License

MIT