HomeUser GuidesAccess WorkspacesWeb Terminal

Web Terminal

On this page

The Web Terminal is a browser-based terminal interface that provides instant access to your workspace's shell environment directly from the Coder dashboard. It's automatically enabled for all workspaces and requires no additional configuration.

Terminal Access

Overview

The Web Terminal leverages xterm.js, an industry-standard terminal emulator, combined with WebSocket technology to provide a responsive and feature-rich terminal experience in your browser.

Key Features

Instant Access: Click the terminal icon in your workspace to open a shell session
Persistent Sessions: Sessions are maintained using reconnection tokens, allowing you to resume your terminal even after page refreshes or network interruptions
Full Unicode Support: Displays international characters and emojis correctly
Clickable Links: Automatically detects and makes URLs clickable
Copy/Paste Support: Select text to automatically copy it to your clipboard
Multiple Rendering Options: Choose between different rendering engines for optimal performance

Accessing the Terminal

From the Dashboard

Navigate to your workspace in the Coder dashboard
Click the Terminal button or icon
The terminal will open in a new browser tab or window

The terminal automatically connects to your workspace agent using an optimized WebSocket connection.

Direct URL Access

You can also bookmark or share direct terminal URLs:

https://coder.example.com/@username/workspace-name/terminal

To access a specific agent in a multi-agent workspace:

https://coder.example.com/@username/workspace-name.agent-name/terminal

Architecture

How It Works

The Web Terminal creates a persistent connection between your browser and the workspace:

Browser: Renders the terminal using xterm.js
WebSocket: Maintains a persistent, low-latency connection
Coder Server: Routes traffic between browser and workspace
Workspace Agent: Manages the pseudo-terminal (PTY) session
Shell Process: Your actual bash/zsh/fish shell

The connection flow is: Browser ↔ WebSocket ↔ Coder Server ↔ Workspace Agent ↔ Shell Process

Reconnection & Persistence

The terminal uses reconnection tokens to maintain session state:

Each terminal session has a unique UUID
If the connection drops, the same token is used to reconnect
The workspace agent buffers output during disconnections
Your shell session continues running even when the browser is closed

Customization

Font Selection

You can customize the terminal font through your user settings:

Click your avatar in the top-right corner
Select Settings → Appearance
Choose from available fonts:
- Geist Mono (default)
- IBM Plex Mono
- Fira Code (with ligatures)
- JetBrains Mono
- Source Code Pro

The font change applies immediately to all open terminal sessions.

Rendering Engine

Administrators can configure the terminal renderer for performance optimization:

# In your Coder deployment configuration
webTerminalRenderer: "canvas"  # Options: canvas, webgl, dom

Or via environment variable:

CODER_WEB_TERMINAL_RENDERER=canvas

Renderer Options:

canvas (default): Best compatibility, good performance on most systems
webgl: Hardware-accelerated, ideal for high-refresh terminals and complex rendering
dom: Fallback option, useful for accessibility tools or older browsers

Note: The renderer setting is deployment-wide and requires a Coder server restart to take effect.

Keyboard Shortcuts

The Web Terminal supports standard terminal keybindings:

Shortcut	Action
`Ctrl+Shift+C` (Mac: `Cmd+Shift+C`)	Copy selected text
`Ctrl+Shift+V` (Mac: `Cmd+Shift+V`)	Paste from clipboard
`Shift+Enter`	Insert literal newline
`Ctrl+C`	Send interrupt (SIGINT)
`Ctrl+D`	Send EOF / exit shell
`Ctrl+Z`	Suspend process (SIGTSTP)

Copy/Paste Behavior

Auto-copy: Selecting text automatically copies it to your clipboard
Paste: Use the standard paste shortcut or middle-click (on Linux/X11)
Browser permissions: First paste may prompt for clipboard access

URL Handling

The terminal automatically detects URLs and makes them clickable. When you click a URL:

External URLs (e.g., https://example.com) open in a new tab
Localhost URLs (e.g., http://localhost:3000) are automatically port-forwarded through Coder's port forwarding system
Port-forwarded URLs use your configured workspace proxy

This makes it seamless to open development servers running in your workspace.

Advanced Usage

Custom Commands

You can open a terminal with a specific command by adding a query parameter:

https://coder.example.com/@user/workspace/terminal?command=htop

When a ?command= parameter is present, a confirmation dialog is shown before the command executes. The user must click Run command to proceed or Cancel to close the terminal window. This prevents external links from silently executing arbitrary commands in a workspace.

Template-configured apps that use the command attribute in coder_app are trusted and bypass the confirmation dialog. These apps use the ?app= parameter internally, which resolves the command from the agent's app list.

Container Selection

For workspaces with multiple Docker containers, specify which container to connect to:

https://coder.example.com/@user/workspace/terminal?container=sidecar

You can also specify the container user:

https://coder.example.com/@user/workspace/terminal?container=app&container_user=node

Note: This feature only works with Docker containers.

Debug Mode

Enable debug information to monitor connection latency:

https://coder.example.com/@user/workspace/terminal?debug

This displays the current latency to your selected workspace proxy in the bottom-right corner.

Configuration File Support

The Web Terminal uses xterm.js under the hood, which is configured programmatically rather than through a configuration file. However, you can customize various aspects:

User-Side Customization

End-users can customize:

Font family via Settings → Appearance
Shell environment via dotfiles or shell rc files
TERM variable is automatically set to xterm-256color

Shell Configuration

The terminal respects your shell's configuration files:

# ~/.bashrc or ~/.zshrc
export PS1="\u@\h:\w\$ "  # Custom prompt
alias ll="ls -lah"         # Custom aliases

# Set terminal colors
export CTERM=xterm-256color

Troubleshooting

Connection Issues

If the terminal fails to connect:

Check workspace status: Ensure your workspace is running
Verify agent health: Look for agent connection warnings
Network issues: Check if WebSockets are blocked by your firewall/proxy
Browser console: Open DevTools to see WebSocket error messages

Display Issues

If characters or colors appear incorrect:

Unicode support: Ensure your shell locale is set correctly (locale -a)
Terminal type: The terminal sets TERM=xterm-256color automatically
Color schemes: Some applications may not render correctly in dark mode
Font rendering: Try switching terminal fonts in your appearance settings