Portal #

A small native Zig listener that makes a computer available as a Letta execution environment without embedding Node, Bun, or the Letta Code bundle.

Performance #

Measured on the same Linux host over 10 real api.letta.com routed turns, after 2 warmups. Portal was built with -Doptimize=ReleaseSmall (ReleaseSmall performed roughly the same as ReleaseFast with a ~13x smaller binary).

Current scope #

• Registers with the Letta environments API and maintains the listener WebSocket heartbeat.
• Implements the v0.31.12 v2-input sync, status, runtime-start, input-ack, and teleport contracts.
• Streams bounded SSE events from the public conversation messages API directly to the listener connection.
• Executes Read, LS, Glob, and literal Grep locally.
• Enables Bash only when the runtime starts in acceptEdits or bypassPermissions mode.
• Continues Cloud turns with native tool results, including inbound and outbound teleport continuations.
• Preserves accepted turns and teleport recovery state across listener WebSocket reconnects.

Build and test #

zig build --fetch
zig build -Doptimize=ReleaseSmall
zig build test -Doptimize=ReleaseSafe

Cross-compile examples:

zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-linux-musl
zig build -Doptimize=ReleaseSmall -Dtarget=aarch64-linux-musl
zig build -Doptimize=ReleaseSmall -Dtarget=aarch64-macos
zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-macos
zig build -Doptimize=ReleaseSmall -Dtarget=x86_64-windows-gnu

Run #

export LETTA_API_KEY=...
./zig-out/bin/portal --env-name portal-dev

Optional environment variables:

• LETTA_CLOUD_API_URL — defaults to https://api.letta.com.
• PORTAL_DEVICE_ID — stable device identifier; defaults to HOSTNAME, COMPUTERNAME, then portal-device.

Compatibility strategy #

test/upstream_compat.zig mirrors wire fixtures from Letta Code v0.31.12 (787b856f) for fast local checks.

The upstream harness runs the actual v0.31.12 listener tests plus a Portal binary adapter inside that checkout. The adapter compares registration contracts and exercises Portal sync, teleport probe, runtime start, input acceptance, Cloud turn, native Read, and approval continuation behavior:

LETTA_CODE_REPO=/path/to/letta-code-v0.31.12 test/run-upstream-compat.sh

Benchmark #

bench/collect.py drives repeated routed turns through letta -p --computer, captures stream timing, and samples both the caller and (over SSH) the remote Linux listener process tree. bench/compare.py compares two reports. See bench/README.md for the Portal-vs-Letta-Code procedure.

The routed headless driver used approximately the same resources in both runs (~357 MB RSS and ~3 s CPU), isolating the difference to the listener process. End-to-end latency is intentionally omitted: these runs used real model/network traffic with unequal output sizes, and routed letta -p did not expose streaming TTFT. Exact ratios should be treated as preliminary until reproduced with deterministic workloads.

PoC limitations #

• Split control/stream listener sockets and paired listener generations are not advertised yet; the legacy single-socket path is used.
• Runtime and teleport recovery state is in memory and does not survive a Portal process restart.
• Portal runs one turn at a time with a bounded queue of eight accepted turns.
• Grep is literal substring matching, not regex-compatible with Letta Code.
• Full queue recovery, interactive approvals, MemFS, MCP, channels, cron, mods, terminal sessions, and self-update are not implemented.
• The repository does not have a project license yet. The vendored websocket.zig dependency is MIT licensed; Letta Code is Apache-2.0.