CanvasTTY is a spatial Electron desktop for real local terminals and AI-agent CLI sessions. This documentation explains how to run the MVP, preserve its process and visual contracts, and extend it with honest source-backed widgets.
| Guide | What it covers |
|---|---|
| Getting started | Requirements, local launch, first session, and verification commands |
| Built-in browser and audit log | Canvas controls, settings, agent access, website/file boundaries, activity, and persistent redacted audit files |
| File browser and reader | Opening a Files card, session and folder roots, supported content, read limits, quick open, persistence, and read-only security boundaries |
| Web companion | Tailscale Serve HTTPS setup, browser pairing, session grants, revocation, and security limits |
| CanvasLink for Android (alpha) | Full-window LAN streaming, touch/keyboard input, APK build, security boundaries and platform limits |
| Installing, releases, and local data | Installer formats, unsigned-preview caveats, credential boundaries, and release checks |
| Widget authoring | Source-level extension paths, visual grammar, process boundaries, and an AI-agent brief |
| Pixel terminal themes (Russian) | Ten-PNG ZIP layout, terminal apertures, app import, and local agent CLI |
| Create a pixel theme with an agent | Zero-context agent brief, exact install ZIP, visual checks, and validation |
| Runtime plugins | Manifest v1, permissions, HOME widgets, canvas apps, separate windows, player media/playlist APIs, SDK, and install flow |
| Animated mascots | PNG/JPEG intake, a Codex creation session, live previews, frame review, transparent cards, approved installation, and retry diagnostics |
| Metrics and telemetry | Subscription limits, session token usage, source priority, privacy, stale states, and tests |
| Terminal renderer transition check | Manual hide/restore check for the DOM/WebGL transition snapshot |
| Security policy | Supported release, vulnerability reporting, local data boundaries, plugins, media grants, browser storage, and audit logs |
| Changelog | User-visible fixes and features by release |
| Contract | Read it before… |
|---|---|
| Architecture | changing IPC, PTY/browser lifecycle, persistence, process ownership, agent transports, or provider adapters |
| UI contract | changing Home, launch flow, Settings, canvas behavior, terminal/browser cards, or visual semantics |
CanvasTTY supports static runtime plugins through manifest API v1. Untrusted UI stays inside sandboxed frames/windows and receives only explicitly approved capabilities. Trusted core integrations that need new main-process services remain source-level contributions compiled with the app.
Never invent session status, counters, quota, token usage, cost, countdowns, or progress. Use a real structured source and surface loading, stale, unavailable, or error when the source cannot answer.
Back to the repository overview.
CanvasTTY is released under the MIT License.