docs: Sprites exec API analysis and recommendations

[bborn]

Summary

• Analyzes the new Sprites exec API at docs.sprites.dev/api/dev-latest/exec/
• Documents how it can improve the existing sprites integration in PR feat: add Sprites integration for cloud-based Claude execution #103 and PR feat: add web-based UI for taskyou with Fly Sprites integration #160
• Provides concrete code examples for each recommended change

Key Findings

The exec API eliminates the need for tmux on sprites entirely. The current PRs (#103, #160) layer tmux inside the sprite VM and use file-tailing for hook communication. The exec API provides these natively:

Current Approach	Exec API Replacement
tmux sessions	Native exec sessions (persistent, reconnectable)
tmux has-session polling every 2s	cmd.Wait() blocks until exit
tail -f hooks.jsonl	FS Watch WebSocket or direct stdout streaming
nohup taskd & + polling	Services API with auto-restart
sh -c "cat > file"	Filesystem API (WriteFile)
Manual iptables	Network Policy API

Recommendations (priority order)

1. Replace tmux with exec sessions — biggest win, removes dependency
2. Session reconnection on restart — critical reliability improvement
3. Filesystem API for setup — cleaner, no shell escaping
4. Network Policy — security improvement
5. Port notifications — UX improvement for dev servers
6. Services API — cleaner process management (PR feat: add web-based UI for taskyou with Fly Sprites integration #160)

Note

The sprites-go SDK already supports all these features — they just need to be used. No SDK upgrade required.

See docs/sprites-exec-api.md for full analysis with code examples.

🤖 Generated with Claude Code