eBPF

Yeet scripts can load a compiled eBPF object (.bpf.o), bind to its maps, and stream ringbuf events back into JavaScript.

Importing

Any path ending in .bpf.o resolves to a default-exported BpfObject:

import probe from './probe.bpf.o';

The file is not read at import time — the ELF is loaded when BpfObject.start() is called.

O BpfObject

A chainable builder representing a compiled eBPF program. Configure binds and attaches, then call start() to load it.

M BpfObject.bind

bind(name: string, opts: { capacity?: number }): BpfObject

Declares a binding for the named map. Returns this for chaining. Must be called before start().

Parameter	Type	Description
name	string	Name of the map as it appears in the ELF.
opts.capacity	number	(RingBuf only) In-process broadcast buffer size in entries.

M BpfObject.attach

attach(prog_name: string, opts: object): BpfObject

Declares an attachment for the named program. Returns this for chaining. Must be called before start().

Parameter	Type	Description
prog_name	string	Name of the program as it appears in the ELF.
opts	object	Attachment options. Reserved for future use — pass {}.

M BpfObject.start

start(): Promise<{ blob_id: string }>

Loads the ELF, runs the verifier, and attaches all declared programs. Resolves to { blob_id } — a string identifying the running instance. Rejects with { code, message } on failure — common causes: bad ELF path, verifier rejection, missing CAP_BPF.

Subsequent calls return immediately with the existing { blob_id }.

P BpfObject.loaded

loaded: boolean

true once start() has completed successfully.

M BpfObject.<mapName>.subscribe

subscribe(cb: (event: any) => void): void

Streams ringbuf events from the named map. Maps are accessed as dynamic properties by name. Each event is decoded to a plain JS object via the map's BTF. Must be called after start().

M BpfObject.<mapName>.read

read(key: any): Promise<any>

One-shot read from the named map. Must be called after start().

Full example

import probe from './probe.bpf.o';

probe
  .bind("events", { capacity: 4096 })
  .attach("handle_exec", {});

const { blob_id } = await probe.start();

probe.events.subscribe((event) => {
  console.log(event);
});