Spaces:
Paused
Paused
| # 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) | |