> For the complete documentation index, see [llms.txt](https://adaptix-framework.gitbook.io/adaptix-framework/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adaptix-framework.gitbook.io/adaptix-framework/development/extenders/agent-plugin/terminals.md).

# Terminals

Terminals provide an interactive shell on the target machine via WebSocket connection with the GUI.

### Flow

```
┌──────────────────────────────────────────────────────────────────────────────────┐
│                              TERMINAL FLOW                                       │
├──────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ╔════════════════════════════════════════════════════════════════════════════╗  │
│  ║                          OPEN TERMINAL                                     ║  │
│  ╚════════════════════════════════════════════════════════════════════════════╝  │
│                                                                                  │
│  GUI ──> WS /channel (agent/terminal, data=base64(agentId|termId|...))           │
│                   │                                                              │
│                   V                                                              │
│  ┌─────────────────────────────────────────────────────────────────────────────┐ │
│  │ TEAMSERVER                                                                  │ │
│  │         │                                                                   │ │
│  │         V                                                                   │ │
│  │  TsAgentTerminalCreateChannel(terminalData, wsconn)                         │ │
│  │         │                                                                   │ │
│  │         ├──> Decode: agentId, terminalId, program, sizeH, sizeW             │ │
│  │         ├──> Create Terminal with Pipes (prSrv, pwSrv, prTun, pwTun)        │ │
│  │         │                                                                   │ │
│  │         V                                                                   │ │
│  │  ┌───────────────────────────────────────────────────────────────────────┐  │ │
│  │  │ EXTENDER (Agent Plugin)                                               │  │ │
│  │  │         │                                                             │  │ │
│  │  │         V                                                             │  │ │
│  │  │  TerminalCallbacks.Start(terminalId, program, sizeH, sizeW)           │  │ │
│  │  │         │                                                             │  │ │
│  │  │         └──> return TaskData (added to agent queue)                   │  │ │
│  │  │                                                                       │  │ │
│  │  └───────────────────────────────────────────────────────────────────────┘  │ │
│  │                                                                             │ │
│  └─────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                  │
│  ╔════════════════════════════════════════════════════════════════════════════╗  │
│  ║                          AGENT STARTS PROCESS                              ║  │
│  ╚════════════════════════════════════════════════════════════════════════════╝  │
│                                                                                  │
│  Agent ──> COMMAND_TERMINAL_OUTPUT (process ready)                               │
│                   │                                                              │
│                   V                                                              │
│  ┌─────────────────────────────────────────────────────────────────────────────┐ │
│  │ EXTENDER (Agent Plugin - ProcessTasksResult)                                │ │
│  │         │                                                                   │ │
│  │         V                                                                   │ │
│  │  ┌───────────────────────────────────────────────────────────────────────┐  │ │
│  │  │ TEAMSERVER                                                            │  │ │
│  │  │         │                                                             │  │ │
│  │  │         V                                                             │  │ │
│  │  │  TsTerminalConnResume(agentId, terminalId, ioDirect)                  │  │ │
│  │  │         │                                                             │  │ │
│  │  │         └──> Start relay goroutines:                                  │  │ │
│  │  │              - WebSocket → pwSrv → prSrv → TaskData → Agent           │  │ │
│  │  │              - Agent → pwTun → prTun → WebSocket                      │  │ │
│  │  │                                                                       │  │ │
│  │  └───────────────────────────────────────────────────────────────────────┘  │ │
│  │                                                                             │ │
│  └─────────────────────────────────────────────────────────────────────────────┘ │
│                                                                                  │
│  ╔════════════════════════════════════════════════════════════════════════════╗  │
│  ║                          DATA FLOW (bidirectional)                         ║  │
│  ╚════════════════════════════════════════════════════════════════════════════╝  │
│                                                                                  │
│  User types ──> WebSocket ──> pwSrv ──> prSrv ──read──>                          │
│         ──> TerminalCallbacks.Write(terminalId, data)                            │
│                 ──> TaskData ──> Agent ──> Process stdin                         │
│                                                                                  │
│  Process stdout ──> Agent ──> TsTerminalConnData(terminalId, data)               │
│         ──> pwTun ──> prTun ──read──> WebSocket ──> GUI                          │
│                                                                                  │
│  ╔════════════════════════════════════════════════════════════════════════════╗  │
│  ║                          TERMINAL CLOSE                                    ║  │
│  ╚════════════════════════════════════════════════════════════════════════════╝  │
│                                                                                  │
│  User closes   ──> TerminalCallbacks.Close(terminalId) ──> TaskData ──> Agent    │
│  Process exits ──> TsTerminalConnClose(terminalId, status) ──> Close WebSocket   │
│                                                                                  │
└──────────────────────────────────────────────────────────────────────────────────┘
```

### Teamserver API for Terminal

```go
type Teamserver interface {
    // Check existence
    TsTerminalConnExists(terminalId string) bool
    
    // Get Pipes for I/O
    TsTerminalGetPipe(AgentId string, terminalId string) (*io.PipeReader, *io.PipeWriter, error)
    
    // Activate relay after successful terminal start
    TsTerminalConnResume(agentId string, terminalId string, ioDirect bool)
    
    // Write data to terminal (from agent)
    TsTerminalConnData(terminalId string, data []byte)
    
    // Close terminal
    TsTerminalConnClose(terminalId string, status string) error
}
```