todoforai/bridge
todoforai/bridge has 83 GitHub stars and 0 forks. GitHot measured +2 stars in 24 hours. Last checked 2026-11-15 16:38 UTC. Last push 2026-11-13.
Measured star growth
- in 24h
- +2
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
TODOforAI Bridge — native C edge agent (PTY relay over Noise-encrypted WebSocket)
AIREADME.md
OriginalTODOforAI Bridge
Native bridge runtime. Connects user machines, Firecracker sandboxes, and cloud VMs to the TODOforAI backend over an encrypted WebSocket channel.
Also ships the agent's in-shell helpers in the same binary: tfa-cat
(let an AI agent see images and PDFs from its terminal), a live tail, and
adb connect to phones — see Shell helpers.
The same binary runs everywhere. Location is a deployment detail; the protocol is uniform.
Design principle
Bridges are islands by default. One guaranteed capability: "accept commands from the backend over WebSocket and execute them." Everything else — SSH, port exposure, overlay networking, language runtimes — is configured by the AI at the user's request by running commands through this same channel.
Wire protocol
TCP → WebSocket → Noise_NX_25519_ChaChaPoly_BLAKE2b → JSON
No TLS. No OpenSSL. All crypto handled by Noise (monocypher + blake2b,
vendored in noise/).
After the Noise handshake, each binary WS frame carries one encrypted JSON message. First encrypted message from edge is auth:
{"type":"auth","deviceId":"dev_...","secret":"..."}
Device credentials are provisioned via todoforai-bridge login (stored on disk by
the shared c-core login helper). Then the v2 multi-session protocol:
identity(→ server, once)exec/input/resize/signal/kill(← server)output/exit/error(→ server)
Server side: backend/src/api/ws/handlers/BridgeHandler.ts.
Layout
| File | Purpose |
|---|---|
main.c |
Event loop, session table, command dispatch |
subcmd.c / .h |
CLI subcommands: login / enroll / whoami; shell helpers tfa-cat, __live, __adb |
conn.c / conn.h |
TCP + WS client handshake + Noise_NX initiator |
util.c / util.h |
Base64 + SHA-1 (for WS-Accept) |
pty.c / pty.h |
forkpty session: read/write/resize/signal |
identity.c / .h |
Host identity gathering (uname, pwd, cwd) |
tools.c / .h |
Probe installed CLI tools via scan_tools function-call |
policy.c / .h |
Device policy: workspace confinement + Landlock jail |
| ws.c / ws.h | RFC 6455 WebSocket client (sync connect, poll loop) |
| json.c / json.h | Minimal JSON parser/writer + base64 |
| noise/ | Vendored noise.c + monocypher (BLAKE2b) |
Build
Only libc + libutil (for forkpty, in libc on macOS).
# Dynamic build (default system cc) — ~190 KB stripped, libc only
make
./build/todoforai-bridge --help
# Static musl build via `zig cc` — ~260 KB, single-file, zero deps
make static
# Windows x64 build via `zig cc` (mingw-w64) — ~240 KB
make release-windows-x64
Run
# First time: provision device credentials (opens browser / device flow)
./build/todoforai-bridge login [--device-name NAME]
# Then connect — defaults to api.todofor.ai:80 (Noise is end-to-end;
# no TLS on the wire — typically Cloudflare/nginx terminates 443 in front)
./build/todoforai-bridge
# Custom server
./build/todoforai-bridge --host 127.0.0.1 --port 4000
# Local-dev: point at a backend on a different host/port
# (Noise TCP RPC port — defaults to api.todofor.ai:4100; for `bun run dev` use 14100)
./build/todoforai-bridge login --host 127.0.0.1 --port 14100
./build/todoforai-bridge enroll --host 127.0.0.1 --port 14100
# Firecracker sandbox: presence of enroll.token=... in /proc/cmdline
# routes to DeviceType.SANDBOX path (?deviceType=SANDBOX).
# Show version / help
./build/todoforai-bridge --version
./build/todoforai-bridge --help
The backend's Noise static public key (the trust anchor for the encrypted
channel) is learned during login via the Noise_NX handshake and persisted
to credentials.json as backendPubkey. All later connections (daemon run,
enroll) pin against it. No flag, no env, no hardcoded default — same flow in
dev, prod, and self-hosted. If the server's identity changes (key rotation,
new deployment), login again to re-learn.
Environment variables
CLI flags take precedence; env vars are fallbacks for non-interactive deployments (sandbox init, systemd units, CI).
| Variable | Used by | Equivalent flag | Purpose |
|---|---|---|---|
NOISE_BACKEND_HOST |
run, login, enroll | --host |
Backend hostname (default api.todofor.ai) |
NOISE_BACKEND_PORT |
login, enroll | --port |
Noise TCP RPC port (default 4100, dev 14100) |
BRIDGE_PORT |
run | --port |
Bridge HTTP/WS port (default 80, dev 4000) |
Updates
The bridge has no HTTP/download logic of its own. Updates ride on the
existing RUN channel (see DeviceService.updateBridge in the backend):
the server sends a shell command that re-runs the sha256-verified
installer over the running binary (rename() over a running binary is
fine on POSIX) with --service — so a systemd/launchd supervisor is
ensured; the installer exits nonzero when none is available, stopping
the chain before the kill — then kills the bridge; the supervisor
relaunches it on the new binary.
Command shape (authoritative version lives in DeviceService.updateBridge) —
note $PPID (the bridge) is the reliable way to find the executable;
inside the RUN shell, $0 is the shell itself:
exe=$(readlink -f /proc/$PPID/exe 2>/dev/null || readlink -f "$(command -v todoforai-bridge)" 2>/dev/null || command -v todoforai-bridge) \
&& [ -x "$exe" ] \
&& i=$(mktemp) && curl -fsSL https://todofor.ai/bridge -o "$i" \
&& sh "$i" --prefix "$(dirname "$exe")" --service \
&& kill $PPID
No new protocol messages, no in-binary HTTP client, no extra dependencies.
Shell helpers (tfa-cat, tail, adb)
Small tools the agent uses inside its bash, built into the bridge binary — no npm/pip install, always the bridge's version. Linux, macOS and Windows.
They don't call the API themselves: they hand bytes to the running bridge
daemon over loopback (127.0.0.1:$TODOFORAI_BRIDGE_PORT, an ephemeral port
exported to every RUN), and the daemon relays them on its already-open Noise
channel (shell:open / shell:data / shell:end → shell:close). No
curl, no TLS handshake per call. The backend accepts a stream only with the
RUN's own token (TODOFORAI_API_TOKEN) for a block that is still running on
this device. See shell_relay.h.
tfa-cat — cat for AI agents that shows images and PDFs to the model
A terminal can't carry an image to an LLM: raw PNG bytes in a PTY are noise,
and the output is capped anyway. tfa-cat is a drop-in cat that fixes this
for the agent's shell:
tfa-cat screenshot.png # the model sees the image in this bash result
tfa-cat a.png report.pdf # several files → several attachments
curl -s "$URL" | tfa-cat # stdin works (type sniffed by magic bytes)
ssh host cat /tmp/x.png | tfa-cat # remote file: run tfa-cat locally
tfa-cat notes.md # text prints exactly like cat
tfa-cat shot.png > copy.png # stdout redirected/piped → raw bytes, like cat
tfa-cat skill:pdf # a skill on this machine (…/skills/pdf/SKILL.md)
tfa-cat skill:pdf/forms.md # another file of that skill
tfa-cat todoforai:todos/<todoId>/plan.md # a TODOforAI file
tfa-cat todoforai:todos/<todoId>/photo.jpg > photo.jpg # …downloaded
tfa-cat todoforai:todos/<todoId> # a folder → its listing
- Formats: PNG, JPEG, GIF, WebP, PDF (≤ 20 MB per command; an image ≤ 3.5 MB, the model APIs' limit — downscale bigger ones).
skill:<name>looks in.agents/skillsand.claude/skillsof the cwd, its parents, then$HOME— local only, no network.todoforai:<path>is resolved by the backend with the RUN's user and the todo's project (what the agent'sreadsees). On the agent's terminal an image/PDF is attached by the backend directly (no bytes travel to the device); anything else — or anything piped/redirected — is streamed down (shell:open {kind:"fetch"}→shell:ready+shell:data→shell:close).- Media goes only to a terminal stdout inside an agent RUN
(
TODOFORAI_BLOCK_IDset): it's attached to the running bash block, and the backend hands it to the agent with that command's result. Prints nothing on success; on failuretfa-cat: <file>: not attached: <reason>, exit 1. - Linux/macOS: a symlink
~/.todoforai/tools/bin/tfa-cat→ the bridge (on PATH in every RUN), dispatched onargv[0]. Windows: atfa-catshell function in the RUN shell →<bridge> __cat.
Live tail, phone adb
cmd | tail -Nwould print nothing until EOF; the RUN shell'stail()wrapper tees the pipe through<bridge> __live, so the chat block shows lines as they come (display only — the tool result is still tail's). The daemon batches and rate-limits them; the pipe itself never waits.adb connect|pair|disconnect "<phone name>"reaches one of the user's phones through the backend's ADB relay (any network; adb's TLS end-to-end). Linux/macOS: a symlink~/.todoforai/tools/bin/adb→ the bridge (on PATH in every RUN, so it also works undertimeout, scripts and subprocesses); every otheradbcommand execs the real adb found later on PATH, andhost:porttargets pass through. Windows: anadbshell function →<bridge> __adb.
Skills (SKILL.md)
The TODOforAI agent discovers skills on a bridge by walking well-known
locations and reading SKILL.md files. Both .agents/skills and
.claude/skills are scanned, per scope:
| Scope | Path | Source |
|---|---|---|
repo |
<workspace-root>/{.agents,.claude}/skills/** |
one per workspace root |
user |
$HOME/{.agents,.claude}/skills/** |
resolved on the bridge device |
Discovery rules (agent/src/agents/skills_info.jl):
- Priority order: repo
.agents→ repo.claude→ user; skills are deduped byname, first match wins. Built-in skills (packages/shared-fbe/builtin-skills/) aretodoforai:skills/<name>/SKILL.md(agentreadand the backend, sotfa-cattoo); nothing is installed on the device, and a device skill with the same name wins. - Walk depth:
find -maxdepth 6; hidden entries (.*) are pruned. - Only files literally named
SKILL.mdare accepted. - Only the first 8 KiB of each file is read for metadata.
- Frontmatter (YAML between leading
---lines) provides:name— skill identifier (falls back to parent directory name)description— full descriptionmetadata.short-description— optional shorter line preferred in the prompt
On a bridge there's no get_skills RPC: the agent runs find + head over
the same machine_exec channel used for shell tools, base64-encoding paths and
file heads so the wire stays ASCII-clean. Skills are listed in the system
prompt (name, description, path); the model opens a SKILL.md with the normal
read tool.
Required tools on the bridge: sh, find, head, base64. Standard on
GNU/BSD/macOS userspace; no extra installation needed.
Notes
- POSIX + Windows (ConPTY, Win10 1809+). Windows build via
make release-windows-x64(zig cc + mingw-w64). On Windows the bridge spawns a POSIX shell inside ConPTY — setBRIDGE_SHELLto override, otherwise it prefers Git for Windows (bash.exeorsh.exe, the same msys2 binary, so an install whosebash.exewas renamed still works), then a PATHbash.exe/sh.exe(skipping the System32 WSL launcher, which isn't a usable POSIX shell here), then a pinned busybox-w32 it provisions itself into%USERPROFILE%\.todoforai\shell\sh.exe, falling back tocmd.exe(RUN/tool catalog assume bash semantics — install Git for Windows).step_pausedworks on Linux, macOS, and Windows; on Windows thepasswordPromptflag is always 0 (the child's ECHO state isn't exposed through the ConPTY API). - Session cap defaults to 256 concurrent PTYs. When full, RUNs evict the least-recently-used idle session (running sessions are never evicted).
- WebSocket uses plain
ws://— TLS is replaced by Noise end-to-end. Typically deployed behind nginx/Cloudflare which terminates external TLS on 443 and forwards plain WS to the backend; the Noise channel runs through it unchanged.
Device policy (optional)
Confines the backend to listed workspaces on this machine. Local-only file, never written by the wire. No file ⇒ full user access (today's behaviour).
todoforai-bridge policy init # allow cwd
todoforai-bridge policy add ~/repo/x
todoforai-bridge policy list # restart bridge to apply
~/.config/todoforai/policy.json (or /etc/todoforai/policy.json, wins):
{ "jail": true, "workspaces": ["/home/me/repo/x"] }
read_file/write_file/ RUNcwdmust be inside a workspace (openat2 RESOLVE_BENEATH— symlink swaps can't escape).- Linux 6.2+: RUN shells and tool probes are Landlock-jailed.
$HOMEis dark except workspaces, toolchain/cache dirs (RW) and shell rc files (RO)."jail": falsedisables (needed on older kernels). - macOS / Windows: path checks only; the shell is not confined.
- Fail closed: bad policy file ⇒ all paths denied, no shells, reason on stderr.
Keep awake while agents work (optional, off by default)
While at least one task runs (a RUN step, incl. parked ones, or an open adb relay stream) the bridge holds an OS system-sleep inhibitor, and drops it ~2 min after the last task ends. Display sleep and screen lock are never touched, nothing wakes a sleeping machine, and nothing is held while idle.
todoforai-bridge config keep-awake on # or off; `config` shows the state
Or the HostCard menu → "Keep awake while agents work". Stored in
<config dir>/config.json ({"keep_awake": true}, next to credentials.json).
The backend may write this file (the UI toggle), so it never holds anything
security-relevant — that is policy.json's job.
| OS | Mechanism |
|---|---|
| Linux | systemd-inhibit --what=sleep --mode=block child (logind). No logind ⇒ log line, no hold. |
| macOS | caffeinate -i child (PreventUserIdleSystemSleep). Lid closed on battery still sleeps. |
| Windows | SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED) |
The helper's stdin is a pipe only the bridge holds, so the hold dies with the
bridge, even on SIGKILL. State goes to the backend as
{"type":"keep_awake_state","enabled":b,"active":b} (→ metadata.keepAwake).
Keep-awake grants no new access: tasks still run as your user. Lock your
screen; Stop in the app ends the task and releases the hold. Check on Linux
with systemd-inhibit --list during a task. The hold is also dropped while
the bridge is disconnected, and --mayfly sessions (tfa-cli --isolated)
don't take one.
Native cloud SSH (ssh tfa-cloud)
On a durable PC bridge the backend can set up plain OpenSSH access to the
user's cloud sandbox (no VPN, no proxy). Advertised as identity.cloudSsh: true; the backend offers it unless switched off (globally CLOUD_SSH_ENABLED=0, or per PC by the owner in the device menu).
Flow: cloud_ssh_offer → bridge ensures ~/.ssh/tfa_cloud (ed25519, created
once by ssh-keygen, never overwritten) → cloud_ssh_key → cloud_ssh_config
(strictly validated: DNS/IP host, port 1–65535, user root, canonical
ssh-ed25519 key of 68 base64 chars, uuid) → writes ~/.ssh/tfa_cloud_config
~/.ssh/tfa_cloud_known_hosts(pinned underHostKeyAlias tfa-cloud-<uuid>), prepends oneIncludeto~/.ssh/config, checksssh -G tfa-cloud, probesssh -o BatchMode=yes -o ConnectTimeout=5 tfa-cloud true→cloud_ssh_ready {ready:true|false}. All disk/ssh work runs in__jobworkers (never on the event loop); one of each kind at a time.
Enabled only for: persistent daemon (not --mayfly), stored/pinned backend
key, no device policy file, POSIX with ssh + ssh-keygen on PATH.
TODOFORAI_CLOUD_SSH=0 opts out.
Limitations (v1):
- POSIX only. Windows never advertises the capability (fails closed).
- Refuses (ready:false, nothing written) when:
~/.ssh/configalready mentionstfa-cloudin aHost/Matchline, is a symlink or not owned by you;tfa_cloud_configwasn't written by the bridge or belongs to another credential profile (first profile wins); the key pair is half-present or the private key is not 0600;~/.sshis group/world-writable. ssh -Gmust resolve to exactly the managed settings. User globals that would also apply totfa-cloud(a global/Host *IdentityFile, a proxy for all hosts) make it not ready instead of being overridden.~/.sshis taken from the passwd entry (as ssh does), not$HOME.- Removal is manual: delete the
Includeline and~/.ssh/tfa_cloud*.
License
MIT, see LICENSE.