Terminal

What it does

terminal is a bundled React module that provides interactive Bash access inside the running Clapilot web container, for maintenance and debugging by administrators. It is a UI-only tool: sessions are short-lived, audited at the lifecycle level, and never exposed to agents.

How to open / enable it

• Web: /modules/terminal (bundled module, slug terminal; manifest bundled-modules/terminal/module.json, renderer: react, categories developer, utilities).
• The module is hidden and unavailable unless Developer mode is enabled, and every API call additionally requires an admin session and the terminal module to be active (src/lib/admin-terminal/access.ts). Deactivating the module through Module Store disables new terminal sessions.
• UI: src/components/modules/terminal-module.tsx. The manifest index.html exists for module package completeness but is not the active runtime while renderer is react.

Key workflows

1. Open /modules/terminal with Developer mode on and an admin session.
2. A PTY session starts with /bin/bash -l (when available) in the mounted Clapilot workspace directory as default cwd.
3. Type commands in the browser terminal; output streams live, and the terminal resizes with the pane.
4. Close the tab or the session explicitly; idle and aged sessions are cleaned up automatically.

Runtime contract

The module uses first-party admin APIs under /api/admin/terminal/** because PTY sessions are process-local and need direct Node runtime access to node-pty:

• Browser terminal: @xterm/xterm (+ fit addon)
• PTY backend: node-pty (src/lib/admin-terminal/session-store.ts)
• Shell: /bin/bash -l when available
• Default cwd: mounted Clapilot workspace directory when available
• Sensitive environment variables (for example ANTHROPIC_*, CLAUDE_*, AWS credential keys) are scrubbed from the session environment before the shell starts.

How the agent can drive it

It cannot — by design. The Terminal module is intentionally not exposed as a chat/live-agent tool; there are no terminal_* agent tools. Agents that need shell execution use their existing native runtime shell/tool contracts instead of this UI-only maintenance terminal.

Configuration & limits

Session limits (from src/lib/admin-terminal/session-store.ts):

• max 3 concurrent sessions per user
• max session age: 1 hour
• idle timeout: 15 minutes (cleanup sweep every 30 seconds)
• input capped at 64 KB per message

Audit behavior

Session lifecycle events are recorded in admin_terminal_audit_events (migration db/migrations/170_admin_terminal_feature.sql, mirrored in bundled-modules/terminal/migrations/001_admin_terminal_audit_events.sql):

• session_started (with cwd, shell, cols/rows, pid metadata)
• session_closed (with reason)
• session_exited (with exit code/signal)

Terminal input and output are not stored.

Troubleshooting

• Module not visible: enable Developer mode; the module stays hidden without it.
• API returns forbidden: the caller must be an admin, Developer mode must be on, and the terminal module must be active in Module Store.
• Session disappears: sessions end automatically after 15 minutes idle or 1 hour total age.