CanvasTTY README

The project's README from github.com/howdeploy/CanvasTTY. As one markdown file: README.md.

https://github.com/user-attachments/assets/444612f7-cda1-4fd6-8514-2f4fac9cc520

English · Русский · 简体中文

Your terminals are places, not tabs.
CanvasTTY is an Electron spatial desktop for real local PTYs and AI-agent CLI sessions. Keep a fixed Home zone, arrange live terminals on an infinite canvas, and see provider limits backed by real data sources.

Stack

Desktop Interface Terminal Providers
Electron
electron-vite		 React
TypeScript		 xterm.js
node-pty		 Codex
Claude · Kimi · OpenCode · Hermes · Grok Build

The application interface currently supports English and Russian. This documentation is also available in Simplified Chinese.

One canvas, real sessions

Launch a shell or agent in a project directory, move and resize its live terminal, zoom out to navigate semantically, and return to Home for sessions, limits, media, and launch shortcuts. CanvasTTY keeps PTY state in the trusted main process and exposes only typed, allow-listed capabilities to the renderer.

Agents, orchestration and protection

Agents start in Auto by default: the CLI's own auto mode (Claude Code, Codex, Grok), CanvasTTY's per-run rules for OpenCode, or, for a CLI without one, its approval bypass only inside agent isolation. Manual, Accept edits, Plan and Bypass are offered only where the CLI has them; Bypass is acknowledged once per CLI and never handed to a subagent. Around every mode sit layers the person controls in Settings → Agents: base protection (hooks that refuse elevation, curl | sh, disk commands and writes outside the project before the tool call runs), delegation rules (a subagent never gets more than its orchestrator and stays in its project; 2 levels and 8 live subagents by default), and an OS isolation layer (macOS sandbox-exec, Linux bubblewrap; none on Windows yet, where subagents run in Manual). When an isolated session ends, CanvasTTY checks the repositories it touched for git settings that would run programs outside isolation and offers to neutralize them.

An Orchestrator session gets the canvastty_agents tools: list_providers (installed agents, sign-in state, models, efforts, profiles), spawn_agent with optional model, effort and profile, wait_for_agent (up to 600 s) and get_agent_result, which returns a Codex or OpenCode subagent's final reply as answer (up to 4,096 characters, masked). See agent orchestration and isolation and protection layers.

Windows shells and provider CLIs

On Windows, the Terminal launcher uses the built-in Windows PowerShell with a clean -NoLogo -NoProfile session, then falls back to pwsh or cmd.exe. Codex, Claude, Qwen Code, Kimi, OpenCode, Hermes, and Grok Build are resolved to a concrete .exe, .com, .cmd, or .bat launcher from the user's PATH or standard per-user CLI directories before they are passed to node-pty/ConPTY.

CanvasTTY does not install provider CLIs. Missing agents remain in Agents settings with an official installation link. After installation, use Check again to refresh the available launchers and limit rows. The launch diagnostic lists checked paths if a CLI is still unavailable.

Install

Download the latest release from GitHub Releases: AppImage/deb for Linux x86_64, installer/portable app for Windows x64, and dmg/zip for Apple Silicon macOS. macOS bundles are ad-hoc signed and verified but do not have a Developer ID signature or Apple notarization; Windows packages remain unsigned. Intel Mac builds are not included yet. Read installing and local-data security.

Or run from source:

npm install
npm run dev

npm run build and packaging also build the native agent helper (canvastty-helper, Go ≥ 1.21, npm run build:helpers) that runs the MCP servers and hooks on macOS and Linux; without Go the app keeps its JavaScript helpers, which Windows uses by default.

Docs

Start here Build on CanvasTTY
Documentation hub Widget authoring
Getting started Metrics and telemetry
Built-in browser and audit log Bundled agent browser skill
Agent orchestration and isolation Bundled orchestration skill
Install, releases, and local data Security policy
Architecture UI contract
Runtime plugin authoring Typed plugin SDK
Changelog MIT license

Even G2 companion

The opt-in Settings → Controls → Even G2 integration adapts CanvasTTY's terminal and AI-agent workflows to Even G2 glasses. Pair with six digits on the same local network, approve access on the computer, then read responses on the glasses HUD, dictate through local Nemotron speech recognition, and create, rename or close shared sessions. The companion includes a More agents picker and supports the desktop's provider list. Its source lives in integrations/even-g2 and builds with the desktop. See setup, distribution status and acceptance limits; a compatible public installer and Even Hub approval are still pending.

Web companion

The opt-in Web companion shares selected sessions with Android, iOS, and desktop browsers through Tailscale Serve HTTPS, not Funnel. CanvasTTY binds its companion endpoint to 127.0.0.1:3481 in this mode; pair with a short-lived code and approve each browser on the desktop. Open Settings → Controls → Web companion for setup, grants, and revocation. End-to-end Tailscale Serve deployment on Windows, Linux, and macOS remains unverified.

Runtime plugins

CanvasTTY includes a permissioned runtime for ready-to-run static GitHub packages: HOME widgets, canvas apps, and separate sandboxed windows. The host SDK now supports persistent user-selected music-library grants, seekable local audio streams, and bounded playlist import/export for full player plugins. See the authoring and security guide, manifest schema, and TypeScript SDK declarations.

Plugin examples:

Built-in agent browser

CanvasTTY includes a core browser rather than a plugin capability: trusted React chrome backed by sandboxed Electron WebContentsView tabs in one persistent Chromium profile. It is available from HOME, restores safe HTTP(S) tabs, keeps website credentials inside Chromium, manages downloads/uploads, and exposes typed browser actions to Claude Code, Codex, Kimi, OpenCode, and Hermes sessions launched by CanvasTTY.

The browser card participates in the same canvas selection, hover-focus, drag, resize, and semantic-zoom model as terminals. Settings controls agent access, tab restore, recent downloads/activity, and browser-data clearing. Agent access uses an authenticated local socket or named pipe and a bundled stdio MCP helper (native on macOS and Linux); it does not open a TCP or remote-debugging port and never exports cookies, passwords, auth headers, local storage, arbitrary JavaScript, or raw CDP.

Every browser command produces a redacted local activity record. Persistent JSONL audit files form a hash chain below Electron userData/browser/audit, rotate at 100 MB, and prune rotated files older than 30 days during store initialization or rotation. Typed/page text, screenshots, credentials, URL queries/fragments, headers, cookies, and tokens are not stored. See the browser and audit-log guide and Architecture.

Quick checks

npm test
npm run test:even
npm run typecheck
npm run build

Contributor acknowledgements

Thanks to @kootik for PR #51: integrating the open pull requests, resolving conflicts, addressing review findings, and improving agent orchestration. The original commits are preserved in the repository history; .mailmap associates their s079891 author identity with kootik.

License

CanvasTTY is released under the MIT License.

CanvasTTY (howdeploy/CanvasTTY)

Searching Database…

110 ·GitHub
CanvasTTY
Что это?CanvasTTY — пространственный рабочий стол на Electron, где настоящие локальные терминалы и CLI-сессии AI-агентов (Claude Code, Codex, Grok, Kimi, OpenCode, Hermes) раскладываются карточками на бесконечном масштабируемом холсте вместо плоских вкладок.
Это десктоп-приложение или CLI-утилита?Это самостоятельное десктоп-приложение на Electron с интерфейсом React/TypeScript, а не библиотека или CLI, которые импортируешь в другой проект.
Как установить и запустить?Скачайте готовый релиз с GitHub Releases (AppImage/deb на Linux x86_64, installer/portable на Windows x64, dmg/zip для macOS на Apple Silicon) или соберите из исходников командой 'npm run build' (и 'npm run build:helpers', если нужен нативный хелпер на Go).
Нужен ли установленный Go для сборки?Go 1.21+ нужен только если вам требуется нативный 'canvastty-helper', запускающий MCP-серверы и хуки на macOS и Linux; без Go приложение переключается на JavaScript-хелперы — это же поведение по умолчанию на Windows.
Скачиваемые сборки полностью подписаны и поддерживаются на всех Mac?Сборки macOS подписаны ad-hoc, но без подписи Developer ID и нотаризации Apple; пакеты Windows не подписаны, сборки для Intel Mac пока не выпускаются, а на Windows нет изоляции сабагентов на уровне ОС (вместо этого они работают в режиме Manual).
На каких десктоп-платформах он работает?CanvasTTY поставляется нативными сборками для Linux (x86_64), Windows (x64) и macOS на Apple Silicon.
Что происходит с моими терминальными и браузерными данными?Состояние PTY остаётся в доверенном главном процессе, встроенный браузер никогда не экспортирует куки, пароли, local storage или исходное содержимое страниц, а активность команд логируется только в обезличенные локальные JSONL-файлы аудита, которые ротируются по достижении 100MB и чистятся через 30 дней.
Как устроены оркестрация агентов и безопасность?Сессия Orchestrator получает инструменты вроде spawnagent, waitforagent и getagentresult для запуска сабагентов Codex или OpenCode; хуки блокируют повышение привилегий, curl-pipe-sh, дисковые команды и записи вне проекта, а слой изоляции ОС (sandbox-exec на macOS, bubblewrap на Linux) дополнительно ограничивает сабагентов максимум 2 уровнями и 8 параллельными экземплярами по умолчанию.
Есть ли встроенный браузер для агентов?Да, CanvasTTY включает базовую браузерную карточку на Chromium, которой агенты вроде Claude Code и Codex могут управлять текстовыми действиями через локальный сокет — без открытия порта удалённой отладки, сырого CDP или хранимых учётных данных.
Можно ли расширять CanvasTTY плагинами?Есть система плагинов времени выполнения с правами доступа для готовых GitHub-пакетов: HOME-виджеты, приложения холста и изолированные окна, с TypeScript SDK и схемой манифеста; среди примеров от сообщества — HUD-виджет Hermes и плеер музыкальной библиотеки.
Что за функция сопряжения с Even G2?Это опциональная интеграция: умные очки Even G2 подключаются по локальной сети, чтобы видеть ответы агентов на HUD, диктовать через локальное распознавание речи и управлять общими сессиями прямо с очков.
What are similar projects?evenfire, qwen-code, ai-manager, claudecodeui, codify, munder-difflin, vicoa, Baize
Which topics is it in?kimi, audit-log, electron-app, grok, sandbox, agent-orchestration, electron, multi-agent, agents, mcp-server, desktop, claude
Creator
howdeploy
Size
142.1 MB
Stars
110
Updated
CommitOct 12Releasev1.8.1Oct 12
Age
2mo
Commits · 90 Days