FAQ

What is yeet?

Yeet is a JavaScript runtime for building custom infrastructure tools that observe and act on your system from the kernel boundary. It runs as a single daemon (yeetd) plus a CLI (yeet). You write a script — in JavaScript or TypeScript — that reads live system telemetry or streams events from an eBPF program, and renders the result to your terminal. See Capabilities for what you can build.

Does running the daemon do a lot of egress by default?

No. The daemon does not egress your telemetry by default, and collection is stream-based, not polling — data flows from the kernel only while something is subscribed to it, at the sample interval you ask for. There's no background traffic to a remote endpoint as a side effect of running yeetd.

A script only sends data off the box if you write it to. If your tool calls out — posting an alert to Slack, shipping a metric somewhere — that egress is code you wrote and can see. Nothing leaves the host on its own.

What platforms does yeet run on?

Yeet observes the Linux kernel, so the daemon runs on Linux. On macOS, development runs inside a Linux VM managed for you via Lima. There's no native Windows or macOS daemon.

How do I install yeet?

Install the daemon and CLI from the package, then start the daemon. Run yeet version to confirm it's up. See the install guide for your distribution's .deb / .rpm.

How do I run a script?

yeet run script.js

This spawns an isolate for the script and attaches your terminal to it. Add --watch to re-run on save, --detach to run without holding your terminal, and --record <file.gif> to capture the session as an animated GIF. Press Ctrl+C to stop.

What can a script see?

Scripts read live system state through the system graph: processes, CPU, memory, network interfaces, kernel stats, Docker containers, NVIDIA GPUs, and hardware sensors. Run yeet graph dump for the full schema, or yeet graph query '<gql>' to probe any field from the shell. Scripts can also load eBPF programs and stream events back from the kernel.

What can't a script do?

The script sandbox is intentionally narrow. There's no fs, fetch, require, node_modules, process, or bare-specifier imports — it isn't Node. Scripts get the system graph, eBPF, the TUI stack, a scheduler (setTimeout / setInterval), and ES module imports resolved relative to the script. Use yeet.exit() to terminate — there's no process.exit.

How do I see what scripts are running?

yeet ps

This lists live isolates with their ID, status, uptime, evaluation time, heap usage, and name. To stop one:

yeet kill <id>

Can I write scripts in TypeScript?

Yes. Scripts can be authored in .ts, .tsx, and .jsx — yeet transpiles them before loading. JSX renders to yeet's own terminal-UI widget library, so you can lay out a live dashboard the way you'd lay out a web app.

How do subscriptions work?

You subscribe to a query against the system graph and provide a callback. The callback runs once per sample at the interval_ms you specify:

const ticket = yeet.graph.subscribe(
  `subscription { kernel_stats(interval_ms: 1000) { ... } }`,
  (sample) => { /* runs every second */ },
);

// later:
await yeet.graph.unsubscribe(ticket);

See yeet.graph.subscribe for the full API.

Can yeet send alerts?

Yes. yeet.alert posts to Slack: connect your workspace once at yeet.cx/settings, and any script can send to a channel from inside a subscription callback. Because the callback already holds the data, an alert is just a threshold check plus a yeet.alert call.

What units does the system graph use?

Units are part of the typed schema. Run yeet graph dump to see the full SDL, or yeet graph query '<gql>' to inspect any field directly.

Can I observe inside a container?

Yes. Probes can attach inside arbitrary network and PID namespaces, and you can target a container by name. The system graph also has container and cgroup nodes, so a script can scope itself to one container without reinventing target selection.