| # Terminal |
|
|
| The integrated terminal provides a full-featured terminal emulator within Automaker, powered by xterm.js. |
|
|
| ## Configuration |
|
|
| Configure the terminal via environment variables in `apps/server/.env`: |
|
|
| ### Disable Terminal Completely |
|
|
| ``` |
| TERMINAL_ENABLED=false |
| ``` |
|
|
| Set to `false` to completely disable the terminal feature. |
|
|
| ### Password Protection |
|
|
| ``` |
| TERMINAL_PASSWORD=yourpassword |
| ``` |
|
|
| By default, the terminal is **not password protected**. Add this variable to require a password. |
|
|
| When password protection is enabled: |
|
|
| - Enter the password in **Settings > Terminal** to unlock |
| - The terminal remains unlocked for the session |
| - You can toggle password requirement on/off in settings after unlocking |
|
|
| ## Keyboard Shortcuts |
|
|
| When the terminal is focused, the following shortcuts are available: |
|
|
| | Shortcut | Action | |
| | -------- | --------------------------------------- | |
| | `Alt+T` | Open new terminal tab | |
| | `Alt+D` | Split terminal right (horizontal split) | |
| | `Alt+S` | Split terminal down (vertical split) | |
| | `Alt+W` | Close current terminal | |
|
|
| These shortcuts are customizable via the keyboard shortcuts settings (Settings > Keyboard Shortcuts). |
|
|
| ### Split Pane Navigation |
|
|
| Navigate between terminal panes using directional shortcuts: |
|
|
| | Shortcut | Action | |
| | --------------------------------- | ------------------------------------ | |
| | `Ctrl+Alt+ArrowUp` (or `Cmd+Alt`) | Move focus to terminal pane above | |
| | `Ctrl+Alt+ArrowDown` | Move focus to terminal pane below | |
| | `Ctrl+Alt+ArrowLeft` | Move focus to terminal pane on left | |
| | `Ctrl+Alt+ArrowRight` | Move focus to terminal pane on right | |
|
|
| The navigation is spatially aware - pressing Down will move to the terminal below your current one, not just cycle through terminals in order. |
|
|
| Global shortcut (works anywhere in the app): |
| | Shortcut | Action | |
| |----------|--------| |
| | `Cmd+`` (Mac) / `Ctrl+`` (Windows/Linux) | Toggle terminal view | |
|
|
| ## Features |
|
|
| ### Multiple Terminals |
|
|
| - Create multiple terminal tabs using the `+` button |
| - Split terminals horizontally or vertically within a tab |
| - Drag terminals to rearrange them |
|
|
| ### Theming |
|
|
| The terminal automatically matches your app theme. Supported themes include: |
|
|
| - Light / Dark / System |
| - Retro, Dracula, Nord, Monokai |
| - Tokyo Night, Solarized, Gruvbox |
| - Catppuccin, One Dark, Synthwave, Red |
|
|
| ### Font Size |
|
|
| - Use the zoom controls (`+`/`-` buttons) in each terminal panel |
| - Or use `Cmd/Ctrl + Scroll` to zoom |
|
|
| ### Scrollback |
|
|
| - The terminal maintains a scrollback buffer of recent output |
| - Scroll up to view previous output |
| - Output is preserved when reconnecting |
|
|
| ## Architecture |
|
|
| The terminal uses a client-server architecture: |
|
|
| 1. **Frontend** (`apps/ui`): xterm.js terminal emulator with WebGL rendering |
| 2. **Backend** (`apps/server`): node-pty for PTY (pseudo-terminal) sessions |
|
|
| Communication happens over WebSocket for real-time bidirectional data flow. |
|
|
| ### Shell Detection |
|
|
| The server automatically detects the best shell: |
|
|
| - **WSL**: User's shell or `/bin/bash` |
| - **macOS**: User's shell, zsh, or bash |
| - **Linux**: User's shell, bash, or sh |
| - **Windows**: PowerShell 7, PowerShell, or cmd.exe |
|
|
| ## Troubleshooting |
|
|
| ### Terminal not connecting |
|
|
| 1. Ensure the server is running (`npm run dev:server`) |
| 2. Check that port 3008 is available |
| 3. Verify the terminal is unlocked |
|
|
| ### Slow performance with heavy output |
|
|
| The terminal throttles output at ~60fps to prevent UI lockup. Very fast output (like `cat` on large files) will be batched. |
|
|
| ### Shortcuts not working |
|
|
| - Ensure the terminal is focused (click inside it) |
| - Some system shortcuts may conflict (especially Alt+Shift combinations on Windows) |
|
|
