# tsl0922/ttyd architecture

> Architecture diagram of the GitHub repository tsl0922/ttyd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsl0922/ttyd
- Repository: https://github.com/tsl0922/ttyd

## Overview

ttyd serves a command's interactive terminal through a browser: the server exposes HTTP and WebSocket endpoints, authenticates clients, starts a PTY process, and transports terminal input/output; the frontend renders the session with xterm. README capabilities include file transfer, Sixel, TLS, configurable commands, authentication, and client limits. Backend relationships are grounded in excerpts or the SOURCE INDEX; HTTP routing internals and several documented optional capabilities were not sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`src/protocol.c`](https://github.com/tsl0922/ttyd/blob/main/src/protocol.c) (WebSocket protocol), [`html/src/components/terminal/xterm/index.ts`](https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/index.ts) (Xterm and transport), [`src/server.c`](https://github.com/tsl0922/ttyd/blob/main/src/server.c) (CLI configuration), [`src/pty.c`](https://github.com/tsl0922/ttyd/blob/main/src/pty.c) (PTY runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and HTTP"]
  node_cli["CLI configuration<br/>[server.c]"]
  node_http["HTTP endpoints<br/>[http.c]"]
  node_embedded_ui["Embedded UI<br/>[html.h]"]
  node_ws_protocol["WebSocket protocol<br/>[protocol.c]"]
  node_server_state["Server state<br/>[server.h]"]
end

subgraph group_session["PTY session"]
  node_terminal_process["Command process<br/>[protocol.c]"]
  node_pty_runtime["PTY runtime<br/>[pty.c]"]
  node_event_loop["Event loop<br/>[server.h]"]
end

subgraph group_browser["Browser terminal"]
  node_web_client["Web client app<br/>[app.tsx]"]
  node_terminal_view["Terminal view<br/>[index.tsx]"]
  node_xterm_client["Xterm and transport<br/>[index.ts]"]
end

subgraph group_extensions["Terminal extensions"]
  node_overlay["Resize overlay<br/>[overlay.ts]"]
  node_file_transfer["File transfer<br/>[zmodem.ts]"]
  node_modal["Transfer dialog<br/>[index.tsx]"]
end

node_operator(("Operator"))
node_browser_user(("Browser user"))
node_external_command["Configured command"]
node_websocket_client["Browser WebSocket"]
node_tls["TLS support"]
node_transfer_tools["ZMODEM / trzsz"]

node_operator -->|"configures"| node_cli
node_cli -->|"sets options"| node_server_state
node_browser_user -->|"opens terminal"| node_web_client
node_web_client -->|"renders"| node_terminal_view
node_terminal_view -->|"opens and connects"| node_xterm_client
node_xterm_client -->|"uses"| node_websocket_client
node_websocket_client -.->|"sends messages"| node_ws_protocol
node_http -->|"serves UI"| node_embedded_ui
node_http -->|"reads configuration"| node_server_state
node_ws_protocol -->|"checks options"| node_server_state
node_ws_protocol -->|"spawns"| node_terminal_process
node_terminal_process -->|"starts via"| node_pty_runtime
node_terminal_process -->|"executes"| node_external_command
node_pty_runtime -->|"uses"| node_event_loop
node_pty_runtime -->|"reports output"| node_ws_protocol
node_ws_protocol -.->|"streams terminal data"| node_xterm_client
node_xterm_client -->|"uses"| node_overlay
node_xterm_client -->|"uses"| node_file_transfer
node_terminal_view -->|"renders"| node_modal
node_file_transfer -->|"requests file selection"| node_modal
node_file_transfer -->|"supports"| node_transfer_tools
node_operator -->|"can enable"| node_tls
node_cli -.->|"configures"| node_tls

click node_cli "https://github.com/tsl0922/ttyd/blob/main/src/server.c"
click node_http "https://github.com/tsl0922/ttyd/blob/main/src/http.c"
click node_embedded_ui "https://github.com/tsl0922/ttyd/blob/main/src/html.h"
click node_ws_protocol "https://github.com/tsl0922/ttyd/blob/main/src/protocol.c"
click node_server_state "https://github.com/tsl0922/ttyd/blob/main/src/server.h"
click node_terminal_process "https://github.com/tsl0922/ttyd/blob/main/src/protocol.c"
click node_pty_runtime "https://github.com/tsl0922/ttyd/blob/main/src/pty.c"
click node_event_loop "https://github.com/tsl0922/ttyd/blob/main/src/server.h"
click node_web_client "https://github.com/tsl0922/ttyd/blob/main/html/src/components/app.tsx"
click node_terminal_view "https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/index.tsx"
click node_xterm_client "https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/index.ts"
click node_overlay "https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/addons/overlay.ts"
click node_file_transfer "https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/addons/zmodem.ts"
click node_modal "https://github.com/tsl0922/ttyd/blob/main/html/src/components/modal/index.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_http,node_embedded_ui,node_ws_protocol,node_server_state,node_browser_user,node_websocket_client toneBlue
class node_terminal_process,node_pty_runtime,node_event_loop toneAmber
class node_web_client,node_terminal_view,node_xterm_client toneMint
class node_overlay,node_file_transfer,node_modal toneRose
class node_operator,node_external_command,node_tls,node_transfer_tools toneIndigo
```

## Components

### Server and HTTP

- [CLI configuration](https://github.com/tsl0922/ttyd/blob/main/src/server.c): `src/server.c`
- [HTTP endpoints](https://github.com/tsl0922/ttyd/blob/main/src/http.c): `src/http.c`
- [Embedded UI](https://github.com/tsl0922/ttyd/blob/main/src/html.h): `src/html.h`
- [WebSocket protocol](https://github.com/tsl0922/ttyd/blob/main/src/protocol.c): `src/protocol.c`
- [Server state](https://github.com/tsl0922/ttyd/blob/main/src/server.h): `src/server.h`

### PTY session

- [Command process](https://github.com/tsl0922/ttyd/blob/main/src/protocol.c): `src/protocol.c`
- [PTY runtime](https://github.com/tsl0922/ttyd/blob/main/src/pty.c): `src/pty.c`
- [Event loop](https://github.com/tsl0922/ttyd/blob/main/src/server.h): `src/server.h`

### Browser terminal

- [Web client app](https://github.com/tsl0922/ttyd/blob/main/html/src/components/app.tsx): `html/src/components/app.tsx`
- [Terminal view](https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/index.tsx): `html/src/components/terminal/index.tsx`
- [Xterm and transport](https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/index.ts): `html/src/components/terminal/xterm/index.ts`

### Terminal extensions

- [Resize overlay](https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/addons/overlay.ts): `html/src/components/terminal/xterm/addons/overlay.ts`
- [File transfer](https://github.com/tsl0922/ttyd/blob/main/html/src/components/terminal/xterm/addons/zmodem.ts): `html/src/components/terminal/xterm/addons/zmodem.ts`
- [Transfer dialog](https://github.com/tsl0922/ttyd/blob/main/html/src/components/modal/index.tsx): `html/src/components/modal/index.tsx`

### Other components

- **Operator**
- **Browser user**
- **Configured command**
- **Browser WebSocket**
- **TLS support**
- **ZMODEM / trzsz**

## Connections

- Operator → CLI configuration: configures (evidence: `README.md`)
- CLI configuration → Server state: sets options (evidence: `src/server.c`)
- Browser user → Web client app: opens terminal (evidence: `README.md`)
- Web client app → Terminal view: renders (evidence: `html/src/components/app.tsx`)
- Terminal view → Xterm and transport: opens and connects (evidence: `html/src/components/terminal/index.tsx`)
- Xterm and transport → Browser WebSocket: uses
- Browser WebSocket → WebSocket protocol: sends messages
- HTTP endpoints → Embedded UI: serves UI (evidence: `src/http.c`)
- HTTP endpoints → Server state: reads configuration (evidence: `src/http.c`)
- WebSocket protocol → Server state: checks options (evidence: `src/protocol.c`)
- WebSocket protocol → Command process: spawns (evidence: `src/protocol.c`)
- Command process → PTY runtime: starts via (evidence: `src/protocol.c`)
- Command process → Configured command: executes (evidence: `README.md`)
- PTY runtime → Event loop: uses
- PTY runtime → WebSocket protocol: reports output (evidence: `src/protocol.c`)
- WebSocket protocol → Xterm and transport: streams terminal data
- Xterm and transport → Resize overlay: uses (evidence: `html/src/components/terminal/xterm/index.ts`)
- Xterm and transport → File transfer: uses (evidence: `html/src/components/terminal/xterm/index.ts`)
- Terminal view → Transfer dialog: renders (evidence: `html/src/components/terminal/index.tsx`)
- File transfer → Transfer dialog: requests file selection
- File transfer → ZMODEM / trzsz: supports (evidence: `README.md`)
- Operator → TLS support: can enable (evidence: `README.md`)
- CLI configuration → TLS support: configures
