:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import wasmUrl from 'v86/build/v86.wasm?url'
import kernelUrl from './assets/buildroot-bzimage.bin?url'
import assetHashes from './assets/hashes.json'
import jqUrl from './assets/jq-linux-i386.bin?url'
import biosUrl from './assets/seabios.bin?url'
import toolsUrl from './assets/tools-linux-i386.tar.gz.bin?url'
import vgaBiosUrl from './assets/vgabios.bin?url'
import { NinePServer } from './ninepServer'
import packageManifest from './terminal-packages.json'
import { DISPLAY_SCRIPT, TerminalDisplayInput } from './terminalDisplay'
import { TerminalNetplay } from './terminalNetplay'
import { TerminalPackages } from './terminalPackages'
import { TerminalWorkerClient } from './TerminalWorkerClient'
function browserClock(): { timestamp: number; timezone: string } {
const now = new Date()
const offset = now.getTimezoneOffset()
const hours = Math.floor(Math.abs(offset) / 60)
const minutes = String(Math.abs(offset) % 60).padStart(2, '0')
// POSIX timezone offsets have the opposite sign to the displayed UTC offset.
const label = `${offset > 0 ? '-' : '+'}${String(hours).padStart(2, '0')}${minutes}`
return {
timestamp: Math.floor(now.getTime() / 1000),
timezone: offset === 0 ? 'UTC0' : `<${label}>${offset > 0 ? '' : '-'}${hours}:${minutes}`,
}
}
async function verifiedImage(url: string, sha256: string, signal: AbortSignal): Promise<ArrayBuffer> {
const response = await fetch(url, {
signal,
credentials: 'omit',
referrerPolicy: 'no-referrer',
})
if (!response.ok) {
throw new Error(`Terminal download failed (${response.status}). Retry starting the terminal.`)
}
const buffer = await response.arrayBuffer()
const digest = await crypto.subtle.digest('SHA-256', buffer)
const actual = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
if (actual !== sha256) {
throw new Error('Terminal download verification failed. Reload PostHog before trying again.')
}
return buffer
}
export class TerminalRuntime {
private emulator?: TerminalWorkerClient
private removeAbortListener?: () => void
private output = ''
private decoder = new TextDecoder()
private outputBuffer = new Uint8Array(8192)
private outputLength = 0
private outputScheduled = false
private ready = false
private disposed = false
private columns = 80
private rows = 24
private promptTail = ''
private atPrompt = false
private hasPrompt = false
private pendingDirectory?: string
readonly screen = document.createElement('div')
readonly displayInput = new TerminalDisplayInput(
(codes) => this.emulator?.keyboard_send_scancodes(codes),
(buttons) => this.sendMouse('mouse-click', buttons)
)
constructor(
private onOutput: (bytes: Uint8Array) => void,
private onDisplay: (active: boolean) => void = () => {},
private onError: (message: string) => void = () => {}
) {
this.screen.append(document.createElement('canvas'))
}
private sendMouse(event: 'mouse-click' | 'mouse-delta', value: boolean[] | number[]): void {
this.emulator?.send({ type: 'mouse', event, value })
}
moveMouse(x: number, y: number): void {
this.sendMouse('mouse-delta', [x, -y])
}
attachDisplay(container: HTMLElement): void {
container.append(this.screen)
this.emulator?.send({ type: 'display', visible: true })
}
detachDisplay(): void {
this.displayInput.release()
this.screen.remove()
this.emulator?.send({ type: 'display', visible: false })
}
private attachNetplay(emulator: TerminalWorkerClient, netplay?: TerminalNetplay): void {
if (netplay) {
netplay.attach((bytes) => emulator.serial_send_bytes(2, bytes))
emulator.add_listener('serial2-output-byte', (byte: number) => netplay.receive(byte))
}
}
async start(
server: NinePServer,
signal: AbortSignal,
onReady: () => void,
folder = '/posthog/files',
netplay?: TerminalNetplay
): Promise<void> {
if (signal.aborted || this.disposed) {
return
}
const canvas = this.screen.querySelector('canvas')!
if (!canvas.transferControlToOffscreen) {
throw new Error('This browser does not support the terminal display. Try a newer browser.')
}
const [bios, vgaBios, kernel, jq, tools] = await Promise.all([
verifiedImage(biosUrl, '73e3f359102e3a9982c35fce98eb7cd08f18303ac7f1ba6ebfbe6cdc1c244d98', signal),
verifiedImage(vgaBiosUrl, 'a4bc0d80cc3ca028c73dafa8fee396b8d054ce87ebd8abfbd31b06b437607880', signal),
verifiedImage(
// This image's uncached 9P reads work before API file sizes are known; Linux 6.8 clamps them to zero.
kernelUrl,
packageManifest.kernel.sha256,
signal
),
verifiedImage(jqUrl, 'ba996e8ce436973e2f39e2639405a37e8c81ba8c722b71c83996278ad0af16dd', signal),
verifiedImage(toolsUrl, assetHashes.toolsSha256, signal),
])
if (signal.aborted || this.disposed) {
return
}
// The guest's BusyBox tar has no gzip support.
const toolsArchive = await new Response(
new Blob([tools]).stream().pipeThrough(new DecompressionStream('gzip'))
).arrayBuffer()
if (signal.aborted || this.disposed) {
return
}
new TerminalPackages(server.filesystem, signal).mount()
const bin = server.filesystem.directory('bin', server.filesystem.root)
server.filesystem.text('display', bin, DISPLAY_SCRIPT)
server.filesystem.file('jq', bin, async () => ({ bytes: new Uint8Array(jq) })).size = jq.byteLength
server.filesystem.file('tools.tar', bin, async () => ({ bytes: new Uint8Array(toolsArchive) })).size =
toolsArchive.byteLength
const emulator = (this.emulator = new TerminalWorkerClient(
{
wasmUrl: new URL(wasmUrl, window.location.href).href,
bios,
vgaBios,
kernel,
canvas: canvas.transferControlToOffscreen(),
},
server,
(message) => {
this.dispose()
this.onError(message)
}
))
const abort = (): void => this.dispose()
signal.addEventListener('abort', abort, { once: true })
this.removeAbortListener = () => signal.removeEventListener('abort', abort)
this.attachNetplay(emulator, netplay)
let boot = ''
let configured = false
emulator.add_listener('serial1-output-byte', (byte: number) => {
if (this.disposed) {
return
}
if (this.ready && (byte === 17 || byte === 18)) {
this.onDisplay(byte === 17)
}
if (configured && !this.ready && byte === 30) {
this.ready = true
this.resize(this.columns, this.rows)
onReady()
}
})
emulator.add_listener('serial0-output-byte', (byte: number) => {
if (this.disposed) {
return
}
this.atPrompt = false
this.promptTail = (this.promptTail + String.fromCharCode(byte)).slice(-8)
if (this.promptTail.endsWith('\x1b]133;B\x07')) {
this.hasPrompt = true
this.atPrompt = true
if (this.pendingDirectory) {
const folder = this.pendingDirectory
this.pendingDirectory = undefined
this.changeDirectory(folder)
}
}
this.outputBuffer[this.outputLength++] = byte
if (this.outputLength === this.outputBuffer.length) {
this.flushOutput()
}
if (!this.outputScheduled) {
this.outputScheduled = true
queueMicrotask(() => {
this.outputScheduled = false
this.flushOutput()
})
}
if (configured) {
return
}
boot = (boot + String.fromCharCode(byte)).slice(-4096)
if (!configured && boot.endsWith('~% ')) {
configured = true
const clock = browserClock()
const setup = new TextEncoder().encode(
[
`stty rows ${this.rows} cols ${this.columns}`,
'export TERM=xterm-256color',
'unset TZ',
`printf '%s\\n' '${clock.timezone}' > /etc/TZ`,
`date -s @${clock.timestamp} > /dev/null`,
'tar -xf /posthog/bin/tools.tar -C / || exit',
'export EDITOR=nano VISUAL=nano',
'mkdir -p /opt/posthog-packages && mount -t tmpfs -o size=256m tmpfs /opt/posthog-packages || exit',
'ln -sf /opt/posthog-tools/lib/ld-musl-i386.so.1 /lib/ld-musl-i386.so.1',
'cp /posthog/bin/jq /usr/bin/jq && chmod +x /usr/bin/jq || exit',
'cp /posthog/bin/ph /usr/bin/ph && chmod +x /usr/bin/ph || exit',
'cp /posthog/bin/run /usr/bin/run && chmod +x /usr/bin/run || exit',
'cp /posthog/bin/hogql /usr/bin/hogql && chmod +x /usr/bin/hogql || exit',
'[ -e /dev/fd ] || ln -s /proc/self/fd /dev/fd',
'mkdir -p /usr/local/bin && cp /posthog/bin/rm /usr/local/bin/rm && chmod +x /usr/local/bin/rm || exit',
'export PATH=/usr/local/bin:$PATH',
'cp /posthog/bin/open /usr/bin/open && chmod +x /usr/bin/open || exit',
'cp /posthog/bin/display /usr/bin/display && chmod +x /usr/bin/display || exit',
...Object.values(packageManifest.packages).flatMap((pkg) =>
Object.keys(pkg.commands).map(
(command) =>
`cp /posthog/bin/${command} /usr/bin/${command} && chmod +x /usr/bin/${command} || exit`
)
),
'stty -F /dev/ttyS1 raw -echo',
// Detach the control helper so the shell's wait command only waits for user jobs.
'(while read -r command first second; do case "$command" in resize) stty -F /dev/ttyS0 rows "$first" cols "$second";; clock) date -s "@$first" > /dev/null; printf "%s\\n" "$second" > /etc/TZ;; esac; done < /dev/ttyS1 &)',
"alias ls='ls --color=auto'",
"export PS1='\\[\\033[32m\\]posthog\\[\\033[0m\\]:\\[\\033[34m\\]\\w\\[\\033[0m\\] $ \\[\\e]133;B\\a\\]'",
`cd -- '${folder.replaceAll("'", "'\\''")}' || cd /posthog/files`,
'clear',
"printf 'PostHog terminal\\n\\nTry:\\n mc\\n tree -C -L 3\\n nano Unfiled/Notebooks/Foobar.md\\n vi Unfiled/Notebooks/Foobar.md\\n ncdu -r /posthog/files\\n mkdir Research\\n ph tools\\n ph notebooks-list --limit 10 | jq .\\n cat /posthog/README.txt\\n\\nUse your own notebook path. In nano, Ctrl+S saves and Ctrl+X exits.\\nIn vi, save with :wq; quit with :q!. Selecting text copies it.\\nFolder creation and moves update PostHog.\\n\\n'",
'stty echo',
"printf '\\036' > /dev/ttyS1",
'exec /usr/bin/bash --rcfile /posthog/bin/shellrc -i',
].join('\n') + '\n'
)
server.filesystem.file('init.sh', bin, async () => ({ bytes: setup })).size = setup.byteLength
// Source setup from 9P to stay within the guest shell's input limit.
// Parse the bootstrap together so stty cannot flush queued serial input.
emulator.serial0_send(
'stty -echo; mkdir -p /posthog; umount /mnt; mount -t 9p -o trans=virtio,version=9p2000.L,cache=none host9p /posthog && . /posthog/bin/init.sh\n'
)
}
})
await emulator.loaded
if (!this.disposed && !signal.aborted) {
emulator.send({ type: 'display', visible: this.screen.isConnected })
emulator.send({ type: 'run' })
}
}
write(data: string): void {
if (this.ready) {
this.atPrompt = false
this.promptTail = ''
this.emulator?.serial_send_bytes(0, new TextEncoder().encode(data))
}
}
changeDirectory(folder: string): boolean {
if (!this.disposed && !this.hasPrompt) {
this.pendingDirectory = folder
return true
}
if (!this.ready || this.disposed || !this.atPrompt) {
return false
}
this.write(`cd -- '${folder.replaceAll("'", "'\\''")}'\n`)
return true
}
read(): string {
this.flushOutput()
return this.output.slice(-1_000_000)
}
private flushOutput(): void {
if (!this.outputLength || this.disposed) {
return
}
const data = this.outputBuffer.slice(0, this.outputLength)
this.outputLength = 0
this.output += this.decoder.decode(data, { stream: true })
if (this.output.length > 1_100_000) {
this.output = this.output.slice(-1_000_000)
}
this.onOutput(data)
}
syncClock(): void {
if (this.ready && !this.disposed) {
const { timestamp, timezone } = browserClock()
this.emulator?.serial_send_bytes(1, new TextEncoder().encode(`clock ${timestamp} ${timezone}\n`))
}
}
resize(columns: number, rows: number): void {
this.columns = Math.max(20, Math.min(500, Math.floor(columns)))
this.rows = Math.max(5, Math.min(200, Math.floor(rows)))
if (this.ready) {
this.emulator?.serial_send_bytes(1, new TextEncoder().encode(`resize ${this.rows} ${this.columns}\n`))
}
}
dispose(): void {
this.detachDisplay()
this.disposed = true
this.ready = false
this.removeAbortListener?.()
this.removeAbortListener = undefined
this.emulator?.dispose()
this.emulator = undefined
this.output = ''
this.outputLength = 0
}
}