Skip to content

Commit c301a0d

Browse files
mtojekmtojek
authored
docs: add comprehensive Web Terminal documentation (coder#20458)
Fixes: coder#19119
1 parent 6c62136 commit c301a0d

File tree

3 files changed

+249
-3
lines changed

3 files changed

+249
-3
lines changed

‎docs/manifest.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,11 @@
209209
"description": "Use VSCode with Coder in the desktop or browser",
210210
"path": "./user-guides/workspace-access/vscode.md"
211211
},
212+
{
213+
"title": "Web Terminal",
214+
"description": "Use the browser-based terminal to access your workspace",
215+
"path": "./user-guides/workspace-access/web-terminal.md"
216+
},
212217
{
213218
"title": "JetBrains IDEs",
214219
"description": "Use JetBrains IDEs with Coder",

‎docs/user-guides/workspace-access/index.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,18 @@ dashboard.
1212

1313
![Workspace View](../../images/user-guides/workspace-view-connection-annotated.png)
1414

15-
## Terminal
15+
## Web Terminal
1616

17-
The terminal is implicitly enabled in Coder and allows you to access your
18-
workspace through the shell environment set by your template.
17+
The Web Terminal is a browser-based terminal that provides instant access to
18+
your workspace's shell environment. It uses [xterm.js](https://xtermjs.org/)
19+
and WebSocket technology for a responsive terminal experience with features
20+
like persistent sessions, Unicode support, and clickable URLs.
1921

2022
![Terminal Access](../../images/user-guides/terminal-access.png)
2123

24+
Read the complete [Web Terminal documentation](./web-terminal.md) for
25+
customization options, keyboard shortcuts, and troubleshooting guides.
26+
2227
## SSH
2328

2429
### Through with the CLI

‎docs/user-guides/workspace-access/web-terminal.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
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+
![Terminal Access](../../images/user-guides/terminal-access.png)
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

0 commit comments

Comments
 (0)