|
| 1 | +#Web Terminal |
| 2 | + |
| 3 | +The Web Terminal is a browser-based terminal interface that provides instant |
| 4 | +access to your workspace's shell environment directly from the Coder dashboard. |
| 5 | +It's automatically enabled for all workspaces and requires no additional |
| 6 | +configuration. |
| 7 | + |
| 8 | + |
| 9 | + |
| 10 | +##Overview |
| 11 | + |
| 12 | +The Web Terminal leverages[xterm.js](https://xtermjs.org/), an industry-standard |
| 13 | +terminal emulator, combined with WebSocket technology to provide a responsive |
| 14 | +and feature-rich terminal experience in your browser. |
| 15 | + |
| 16 | +###Key Features |
| 17 | + |
| 18 | +-**Instant Access**: Click the terminal icon in your workspace to open a shell |
| 19 | + session |
| 20 | +-**Persistent Sessions**: Sessions are maintained using reconnection tokens, |
| 21 | + allowing you to resume your terminal even after page refreshes or network |
| 22 | + interruptions |
| 23 | +-**Full Unicode Support**: Displays international characters and emojis |
| 24 | + correctly |
| 25 | +-**Clickable Links**: Automatically detects and makes URLs clickable |
| 26 | +-**Copy/Paste Support**: Select text to automatically copy it to your clipboard |
| 27 | +-**Multiple Rendering Options**: Choose between different rendering engines for |
| 28 | + optimal performance |
| 29 | + |
| 30 | +##Accessing the Terminal |
| 31 | + |
| 32 | +###From the Dashboard |
| 33 | + |
| 34 | +1. Navigate to your workspace in the Coder dashboard |
| 35 | +2. Click the**Terminal** button or icon |
| 36 | +3. The terminal will open in a new browser tab or window |
| 37 | + |
| 38 | +The terminal automatically connects to your workspace agent using an optimized |
| 39 | +WebSocket connection. |
| 40 | + |
| 41 | +###Direct URL Access |
| 42 | + |
| 43 | +You can also bookmark or share direct terminal URLs: |
| 44 | + |
| 45 | +```text |
| 46 | +https://coder.example.com/@username/workspace-name/terminal |
| 47 | +``` |
| 48 | + |
| 49 | +To access a specific agent in a multi-agent workspace: |
| 50 | + |
| 51 | +```text |
| 52 | +https://coder.example.com/@username/workspace-name.agent-name/terminal |
| 53 | +``` |
| 54 | + |
| 55 | +##Architecture |
| 56 | + |
| 57 | +###How It Works |
| 58 | + |
| 59 | +The Web Terminal creates a persistent connection between your browser and the |
| 60 | +workspace: |
| 61 | + |
| 62 | +1.**Browser**: Renders the terminal using xterm.js |
| 63 | +2.**WebSocket**: Maintains a persistent, low-latency connection |
| 64 | +3.**Coder Server**: Routes traffic between browser and workspace |
| 65 | +4.**Workspace Agent**: Manages the pseudo-terminal (PTY) session |
| 66 | +5.**Shell Process**: Your actual bash/zsh/fish shell |
| 67 | + |
| 68 | +The connection flow is: Browser ↔ WebSocket ↔ Coder Server ↔ Workspace Agent ↔ Shell Process |
| 69 | + |
| 70 | +###Reconnection & Persistence |
| 71 | + |
| 72 | +The terminal uses reconnection tokens to maintain session state: |
| 73 | + |
| 74 | +- Each terminal session has a unique UUID |
| 75 | +- If the connection drops, the same token is used to reconnect |
| 76 | +- The workspace agent buffers output during disconnections |
| 77 | +- Your shell session continues running even when the browser is closed |
| 78 | + |
| 79 | +##Customization |
| 80 | + |
| 81 | +###Font Selection |
| 82 | + |
| 83 | +You can customize the terminal font through your user settings: |
| 84 | + |
| 85 | +1. Click your avatar in the top-right corner |
| 86 | +2. Select**Settings** →**Appearance** |
| 87 | +3. Choose from available fonts: |
| 88 | +-**IBM Plex Mono** (default) |
| 89 | +-**Fira Code** (with ligatures) |
| 90 | +-**JetBrains Mono** |
| 91 | +-**Source Code Pro** |
| 92 | + |
| 93 | +The font change applies immediately to all open terminal sessions. |
| 94 | + |
| 95 | +###Rendering Engine |
| 96 | + |
| 97 | +Administrators can configure the terminal renderer for performance optimization: |
| 98 | + |
| 99 | +```yaml |
| 100 | +# In your Coder deployment configuration |
| 101 | +webTerminalRenderer:"canvas"# Options: canvas, webgl, dom |
| 102 | +``` |
| 103 | +
|
| 104 | +Or via environment variable: |
| 105 | +
|
| 106 | +```bash |
| 107 | +CODER_WEB_TERMINAL_RENDERER=canvas |
| 108 | +``` |
| 109 | + |
| 110 | +**Renderer Options:** |
| 111 | + |
| 112 | +-**`canvas`** (default): Best compatibility, good performance on most systems |
| 113 | +-**`webgl`**: Hardware-accelerated, ideal for high-refresh terminals and |
| 114 | + complex rendering |
| 115 | +-**`dom`**: Fallback option, useful for accessibility tools or older browsers |
| 116 | + |
| 117 | +>**Note:** The renderer setting is deployment-wide and requires a Coder server |
| 118 | +>restart to take effect. |
| 119 | +
|
| 120 | +##Keyboard Shortcuts |
| 121 | + |
| 122 | +The Web Terminal supports standard terminal keybindings: |
| 123 | + |
| 124 | +| Shortcut| Action| |
| 125 | +|-------------------------------------|---------------------------| |
| 126 | +|`Ctrl+Shift+C` (Mac:`Cmd+Shift+C`)| Copy selected text| |
| 127 | +|`Ctrl+Shift+V` (Mac:`Cmd+Shift+V`)| Paste from clipboard| |
| 128 | +|`Shift+Enter`| Insert literal newline| |
| 129 | +|`Ctrl+C`| Send interrupt (SIGINT)| |
| 130 | +|`Ctrl+D`| Send EOF / exit shell| |
| 131 | +|`Ctrl+Z`| Suspend process (SIGTSTP)| |
| 132 | + |
| 133 | +###Copy/Paste Behavior |
| 134 | + |
| 135 | +-**Auto-copy**: Selecting text automatically copies it to your clipboard |
| 136 | +-**Paste**: Use the standard paste shortcut or middle-click (on Linux/X11) |
| 137 | +-**Browser permissions**: First paste may prompt for clipboard access |
| 138 | + |
| 139 | +##URL Handling |
| 140 | + |
| 141 | +The terminal automatically detects URLs and makes them clickable. When you click |
| 142 | +a URL: |
| 143 | + |
| 144 | +-**External URLs** (e.g.,`https://example.com`) open in a new tab |
| 145 | +-**Localhost URLs** (e.g.,`http://localhost:3000`) are automatically |
| 146 | + port-forwarded through Coder's[port forwarding](./port-forwarding.md) system |
| 147 | +-**Port-forwarded URLs** use your configured workspace proxy |
| 148 | + |
| 149 | +This makes it seamless to open development servers running in your workspace. |
| 150 | + |
| 151 | +##Advanced Usage |
| 152 | + |
| 153 | +###Custom Commands |
| 154 | + |
| 155 | +You can open a terminal with a specific command by adding a query parameter: |
| 156 | + |
| 157 | +```text |
| 158 | +https://coder.example.com/@user/workspace/terminal?command=htop |
| 159 | +``` |
| 160 | + |
| 161 | +This will execute`htop` immediately when the terminal opens. |
| 162 | + |
| 163 | +###Container Selection |
| 164 | + |
| 165 | +For workspaces with multiple Docker containers, specify which container to |
| 166 | +connect to: |
| 167 | + |
| 168 | +```text |
| 169 | +https://coder.example.com/@user/workspace/terminal?container=sidecar |
| 170 | +``` |
| 171 | + |
| 172 | +You can also specify the container user: |
| 173 | + |
| 174 | +```text |
| 175 | +https://coder.example.com/@user/workspace/terminal?container=app&container_user=node |
| 176 | +``` |
| 177 | + |
| 178 | +>**Note:** This feature only works with Docker containers. |
| 179 | +
|
| 180 | +###Debug Mode |
| 181 | + |
| 182 | +Enable debug information to monitor connection latency: |
| 183 | + |
| 184 | +```text |
| 185 | +https://coder.example.com/@user/workspace/terminal?debug |
| 186 | +``` |
| 187 | + |
| 188 | +This displays the current latency to your selected workspace proxy in the |
| 189 | +bottom-right corner. |
| 190 | + |
| 191 | +##Configuration File Support |
| 192 | + |
| 193 | +The Web Terminal uses xterm.js under the hood, which is configured |
| 194 | +programmatically rather than through a configuration file. However, you can |
| 195 | +customize various aspects: |
| 196 | + |
| 197 | +###User-Side Customization |
| 198 | + |
| 199 | +End-users can customize: |
| 200 | + |
| 201 | +-**Font family** via Settings → Appearance |
| 202 | +-**Shell environment** via dotfiles or shell rc files |
| 203 | +-**TERM variable** is automatically set to`xterm-256color` |
| 204 | + |
| 205 | +###Shell Configuration |
| 206 | + |
| 207 | +The terminal respects your shell's configuration files: |
| 208 | + |
| 209 | +```bash |
| 210 | +# ~/.bashrc or ~/.zshrc |
| 211 | +export PS1="\u@\h:\w\$"# Custom prompt |
| 212 | +alias ll="ls -lah"# Custom aliases |
| 213 | + |
| 214 | +# Set terminal colors |
| 215 | +export CTERM=xterm-256color |
| 216 | +``` |
| 217 | + |
| 218 | +##Troubleshooting |
| 219 | + |
| 220 | +###Connection Issues |
| 221 | + |
| 222 | +If the terminal fails to connect: |
| 223 | + |
| 224 | +1.**Check workspace status**: Ensure your workspace is running |
| 225 | +2.**Verify agent health**: Look for agent connection warnings |
| 226 | +3.**Network issues**: Check if WebSockets are blocked by your firewall/proxy |
| 227 | +4.**Browser console**: Open DevTools to see WebSocket error messages |
| 228 | + |
| 229 | +###Display Issues |
| 230 | + |
| 231 | +If characters or colors appear incorrect: |
| 232 | + |
| 233 | +1.**Unicode support**: Ensure your shell locale is set correctly (`locale -a`) |
| 234 | +2.**Terminal type**: The terminal sets`TERM=xterm-256color` automatically |
| 235 | +3.**Color schemes**: Some applications may not render correctly in dark mode |
| 236 | +4.**Font rendering**: Try switching terminal fonts in your appearance settings |