File size: 3,818 Bytes
1dbc34b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 | # 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)
|