### Install Project Dependencies

Source: https://github.com/termix-ssh/termix/wiki/Manual

Run this command after cloning the repository to install all necessary NPM packages.

```sh
npm install
```

--------------------------------

### Check if initial setup is needed

Source: https://context7.com/termix-ssh/termix/llms.txt

Determines if the initial user setup is required, typically when the platform is first deployed.

```APIDOC
## GET /users/setup-required

### Description
Checks if the initial user setup is required on the Termix platform.

### Method
GET

### Endpoint
/users/setup-required

### Response
#### Success Response
- **setupRequired** (boolean) - True if setup is required, false otherwise.
```

--------------------------------

### Check if initial setup is needed

Source: https://context7.com/termix-ssh/termix/llms.txt

Verifies if the initial user setup is required. Useful for determining if the first admin account needs to be created.

```bash
curl http://localhost:8080/users/setup-required
```

--------------------------------

### Start Backend WebSocket Server

Source: https://github.com/termix-ssh/termix/wiki/Manual

Navigate to the src/backend directory and run this command to start the file and database API on ports 8081 and 8082.

```sh
node starter.cjs
```

--------------------------------

### Run Development Servers

Source: https://github.com/termix-ssh/termix/blob/main/CONTRIBUTING.md

Execute these commands to start both the backend and the frontend Vite development servers.

```sh
npm run dev
npm run dev:backend
```

--------------------------------

### Start Termix with Docker Compose

Source: https://github.com/termix-ssh/termix/wiki/Docker

Command to start the Termix service defined in the docker-compose.yml file in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Host Configuration JSON

Source: https://context7.com/termix-ssh/termix/llms.txt

Example JSON object for configuring a host with basic and advanced options, including jump hosts and proxy settings.

```json
{
  "id": 42,
  "name": "My Server",
  "ip": "192.168.1.100",
  "port": 22,
  "username": "root",
  "authType": "password",
  "hasPassword": true,
  "hasKey": false,
  "enableTerminal": true,
  "enableFileManager": true,
  "enableTunnel": true,
  "tags": ["production", "web"],
  "jumpHosts": [],
  "tunnelConnections": [],
  "quickActions": []
}
```

```json
{
  "name": "Jump Target",
  "ip": "10.10.10.10",
  "port": 22,
  "username": "admin",
  "authType": "key",
  "jumpHosts": [{ "hostId": 5 }],
  "portKnockSequence": [
    { "port": 1234, "protocol": "tcp", "delay": 200 },
    { "port": 5678, "protocol": "udp", "delay": 100 }
  ],
  "useSocks5": true,
  "socks5Host": "proxy.example.com",
  "socks5Port": 1080,
  "socks5Username": "proxyuser",
  "socks5Password": "proxypass",
  "terminalConfig": {
    "keepaliveInterval": 30000,
    "keepaliveCountMax": 3,
    "autoTmux": true
  }
}
```

--------------------------------

### Docker Compose for Termix Installation

Source: https://github.com/termix-ssh/termix/blob/main/README.md

This Docker Compose file sets up Termix and its dependencies (like guacd for remote desktop features). Ensure you have Docker and Docker Compose installed. Adjust ports and volumes as needed for your environment.

```yaml
services:
  termix:
    image: ghcr.io/lukegus/termix:latest
    container_name: termix
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - termix-data:/app/data
    environment:
      PORT: "8080"
    depends_on:
      - guacd
    networks:
      - termix-net

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: guacd
    restart: unless-stopped
    ports:
      - "4822:4822"
    networks:
      - termix-net

volumes:
  termix-data:
    driver: local

networks:
  termix-net:
    driver: bridge
```

--------------------------------

### Deploy Termix with Docker Compose

Source: https://context7.com/termix-ssh/termix/llms.txt

Recommended deployment method using Docker Compose. Ensure Docker and Docker Compose are installed. The UI will be accessible at http://localhost:8080.

```yaml
# docker/docker-compose.yml
services:
  termix:
    image: ghcr.io/lukegus/termix:latest
    container_name: termix
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - termix-data:/app/data
    environment:
      PORT: "8080"
    depends_on:
      - guacd
    networks:
      - termix-net

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: guacd
    restart: unless-stopped
    ports:
      - "4822:4822"
    networks:
      - termix-net

volumes:
  termix-data:
    driver: local

networks:
  termix-net:
    driver: bridge
```

```bash
docker compose up -d
# Termix UI is available at http://localhost:8080
```

--------------------------------

### Get All Hosts (Internal)

Source: https://context7.com/termix-ssh/termix/llms.txt

Internal API endpoint to retrieve all host configurations. Requires an internal authentication token.

```bash
curl http://localhost:8080/host/db/host/internal/all \
  -H "x-internal-auth-token: <system-token>"
```

--------------------------------

### Get Autostart-Tunnel Hosts (Internal)

Source: https://context7.com/termix-ssh/termix/llms.txt

Internal API endpoint to retrieve hosts configured for autostart tunnels. Requires an internal authentication token.

```bash
curl http://localhost:8080/host/db/host/internal \
  -H "x-internal-auth-token: <system-token>"
```

--------------------------------

### Internal: Get Autostart-Tunnel Hosts

Source: https://context7.com/termix-ssh/termix/llms.txt

Retrieves a list of hosts configured for autostart tunnels. This endpoint is intended for internal use by the tunnel service.

```APIDOC
## GET /host/db/host/internal

### Description
Internal endpoint to retrieve hosts that are configured to automatically start tunnels. Primarily used by the tunnel service.

### Method
GET

### Endpoint
/host/db/host/internal

### Headers
- **x-internal-auth-token** (string) - Required - Authentication token for internal services.

### Request Example
```bash
curl http://localhost:8080/host/db/host/internal \
  -H "x-internal-auth-token: <system-token>"
```
```

--------------------------------

### OIDC / SSO Configuration and Linking

Source: https://context7.com/termix-ssh/termix/llms.txt

Endpoints for configuring and managing OpenID Connect (OIDC) for Single Sign-On (SSO). Includes storing provider configuration, getting authorization URLs, and linking OIDC identities to password accounts. Admin privileges may be required for configuration.

```bash
# Store OIDC provider config (admin only)
curl -b cookies.txt -X POST http://localhost:8080/users/oidc-config \
  -H "Content-Type: application/json" \
  -d '{
    "issuer": "https://accounts.google.com",
    "clientId": "my-client-id",
    "clientSecret": "my-secret",
    "redirectUri": "http://localhost:8080/users/oidc/callback"
  }'

# Get OIDC authorization URL (redirect user to this)
curl http://localhost:8080/users/oidc/authorize
# Response: { "url": "https://accounts.google.com/o/oauth2/v2/auth?..." }

# Link an OIDC identity to an existing password account
curl -b cookies.txt -X POST http://localhost:8080/users/link-oidc-to-password \
  -H "Content-Type: application/json" \
  -d '{"password": "S3cur3P@ss!"}'
```

--------------------------------

### Internal: Get All Hosts

Source: https://context7.com/termix-ssh/termix/llms.txt

Retrieves all host entries from the database. This endpoint is intended for internal use.

```APIDOC
## GET /host/db/host/internal/all

### Description
Internal endpoint to retrieve all configured hosts. Used by internal services for various operations.

### Method
GET

### Endpoint
/host/db/host/internal/all

### Headers
- **x-internal-auth-token** (string) - Required - Authentication token for internal services.

### Request Example
```bash
curl http://localhost:8080/host/db/host/internal/all \
  -H "x-internal-auth-token: <system-token>"
```
```

--------------------------------

### PermissionManager: RBAC Implementation

Source: https://context7.com/termix-ssh/termix/llms.txt

Manages Role-Based Access Control (RBAC). Use getInstance to get an instance and canAccessHost to check user permissions for a specific host.

```typescript
import { PermissionManager } from './utils/permission-manager.js';

const permissionManager = PermissionManager.getInstance();

// Check a permission before acting on a host
const canAccess = await permissionManager.canAccessHost(userId, hostId);
```

--------------------------------

### Get current user profile

Source: https://context7.com/termix-ssh/termix/llms.txt

Retrieves the profile information for the currently authenticated user.

```APIDOC
## GET /users/me

### Description
Fetches the profile details of the user who is currently logged in.

### Method
GET

### Endpoint
/users/me

### Response
#### Success Response
- **userId** (string) - The unique identifier for the user.
- **username** (string) - The username of the user.
- **isAdmin** (boolean) - Indicates if the user has administrator privileges.
- **totpEnabled** (boolean) - Indicates if Two-Factor Authentication (TOTP) is enabled for the user.
- **oidcLinked** (boolean) - Indicates if the user account is linked via OpenID Connect.
- **dataUnlocked** (boolean) - Indicates if the user's encrypted data store is currently unlocked.
```

--------------------------------

### Guacamole Settings API: Get and Update Settings

Source: https://context7.com/termix-ssh/termix/llms.txt

Retrieves the current Guacamole settings or updates them by providing the guacd host and port.

```bash
# Get settings
curl -b cookies.txt http://localhost:8080/users/guacamole-settings

# Update settings
curl -b cookies.txt -X PATCH http://localhost:8080/users/guacamole-settings \
  -H "Content-Type: application/json" \
  -d '{"guacdHost": "guacd", "guacdPort": 4822}'
```

--------------------------------

### UserCrypto: Per-User Data Encryption

Source: https://context7.com/termix-ssh/termix/llms.txt

Handles per-user data encryption. Use getInstance to get an instance and getUserDataKey to check if the user's data key is unlocked.

```typescript
import { UserCrypto } from './utils/user-crypto.js';

const userCrypto = UserCrypto.getInstance();

// Check whether the user has unlocked their data key
const dataKey = userCrypto.getUserDataKey(userId);
if (!dataKey) {
  return res.status(423).json({ code: 'DATA_LOCKED' });
}
```

--------------------------------

### TOTP / MFA Management

Source: https://context7.com/termix-ssh/termix/llms.txt

Endpoints for managing Time-based One-Time Password (TOTP) for Multi-Factor Authentication (MFA). Includes setup, enabling, disabling, and generating backup codes. Requires cookie authentication for most operations.

```bash
# Setup — returns provisioning URI + QR code data URL
curl -b cookies.txt -X POST http://localhost:8080/users/totp/setup

# Enable after scanning QR code
curl -b cookies.txt -X POST http://localhost:8080/users/totp/enable \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# Disable
curl -b cookies.txt -X POST http://localhost:8080/users/totp/disable \
  -H "Content-Type: application/json" \
  -d '{"password": "S3cur3P@ss!"}'

# Generate backup codes
curl -b cookies.txt -X POST http://localhost:8080/users/totp/backup-codes
```

--------------------------------

### Build Project for Production

Source: https://github.com/termix-ssh/termix/wiki/Manual

Execute this command to build the project for production deployment. It is recommended to host the website via nginx using the provided nginx config.

```sh
npm run build
```

--------------------------------

### Create Host

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates a new host entry in the system.

```APIDOC
## POST /host/db/host — Create a host

Supports `application/json` or `multipart/form-data` (for uploading a private key file).

### Description
Creates a new host entry. Authentication can be via password or by uploading a private key.

### Method
POST

### Endpoint
/host/db/host

### Parameters
#### Request Body (JSON Example)
- **name** (string) - Required - The name of the host.
- **ip** (string) - Required - The IP address of the host.
- **port** (integer) - Optional - The SSH port (defaults to 22).
- **username** (string) - Required - The username for SSH connection.
- **authType** (string) - Required - Authentication type, either "password" or "key".
- **password** (string) - Required if `authType` is "password" - The password for SSH connection.
- **privateKey** (string) - Required if `authType` is "key" - The private key content for SSH connection.
- **enableTerminal** (boolean) - Optional - Whether to enable terminal access (defaults to true).
- **enableFileManager** (boolean) - Optional - Whether to enable file manager access (defaults to true).
- **enableTunnel** (boolean) - Optional - Whether to enable tunneling (defaults to true).
- **tags** (array of strings) - Optional - Tags associated with the host.
```

--------------------------------

### Create a new user account

Source: https://context7.com/termix-ssh/termix/llms.txt

Registers the first admin user or a regular user if registration is open. Requires the username and password.

```bash
curl -X POST http://localhost:8080/users/create \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "S3cur3P@ss!"}'
```

--------------------------------

### Run Project in Development Mode

Source: https://github.com/termix-ssh/termix/wiki/Manual

Use this command to run the project without building. This is not recommended for production environments. The website will be accessible at http://localhost:5173.

```sh
npm run dev
```

--------------------------------

### Register a new user

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates the first (admin) account when no users exist, or a regular account when registration is open. Requires username and password.

```APIDOC
## POST /users/create

### Description
Creates the first (admin) account when no users exist, or a regular account when registration is open.

### Method
POST

### Endpoint
/users/create

### Request Body
- **username** (string) - Required - The desired username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "alice",
  "password": "S3cur3P@ss!"
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message.
- **userId** (string) - The unique identifier for the newly created user.
```

--------------------------------

### Alerts API: Create and List Alerts

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates a new alert with host ID, metric, threshold, and condition, or lists all configured alerts.

```bash
# Create an alert
curl -b cookies.txt -X POST http://localhost:8080/alerts \
  -H "Content-Type: application/json" \
  -d '{"hostId": 42, "metric": "cpu", "threshold": 90, "condition": "gt"}'

# List alerts
curl -b cookies.txt http://localhost:8080/alerts
```

--------------------------------

### Upload SSH Key File via Multipart

Source: https://context7.com/termix-ssh/termix/llms.txt

Use this endpoint to add a new host with private key authentication by uploading the key file using multipart/form-data.

```bash
curl -b cookies.txt -X POST http://localhost:8080/host/db/host \
  -F 'data={"name":"Key Server","ip":"10.0.0.5","port":22,"username":"deploy","authType":"key"}' \
  -F 'key=@/home/user/.ssh/id_rsa'
```

--------------------------------

### Create Host Entry with Password Authentication

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates a new host entry in the database using password authentication. Supports JSON or multipart/form-data for private key uploads. Requires cookie authentication.

```bash
# Password authentication
curl -b cookies.txt -X POST http://localhost:8080/host/db/host \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Server",
    "ip": "192.168.1.100",
    "port": 22,
    "username": "root",
    "authType": "password",
    "password": "hunter2",
    "enableTerminal": true,
    "enableFileManager": true,
    "enableTunnel": true,
    "tags": ["production", "web"]
  }'
```

--------------------------------

### Snippets API: Create a Reusable Shell Snippet

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates a new reusable shell snippet. Requires a name, command, and optional description, sent as JSON.

```bash
# Create a snippet
curl -b cookies.txt -X POST http://localhost:8080/snippets \
  -H "Content-Type: application/json" \
  -d '{"name": "Check disk", "command": "df -h", "description": "Show disk usage"}'
```

--------------------------------

### Perform user login

Source: https://context7.com/termix-ssh/termix/llms.txt

Authenticates a user with username and password. If Multi-Factor Authentication (MFA) like TOTP is enabled, a temporary token is returned for further verification.

```bash
curl -c cookies.txt -X POST http://localhost:8080/users/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "S3cur3P@ss!", "rememberMe": false}'
```

--------------------------------

### Upload SSH Key for Host

Source: https://context7.com/termix-ssh/termix/llms.txt

Uploads a host configuration along with a private SSH key file using multipart form data.

```APIDOC
## POST /host/db/host

### Description
Creates a new host entry, supporting private key authentication by uploading the key file.

### Method
POST

### Endpoint
/host/db/host

### Parameters
#### Form Data
- **data** (json) - Required - Host configuration details including name, ip, port, username, and authType set to 'key'.
- **key** (file) - Required - The private SSH key file.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:8080/host/db/host \
  -F 'data={"name":"Key Server","ip":"10.0.0.5","port":22,"username":"deploy","authType":"key"}' \
  -F 'key=@/home/user/.ssh/id_rsa'
```

### Response
#### Success Response (200)
Returns the created host object with an assigned ID.

### Response Example
```json
{
  "id": 42,
  "name": "My Server",
  "ip": "192.168.1.100",
  "port": 22,
  "username": "root",
  "authType": "password",
  "hasPassword": true,
  "hasKey": false,
  "enableTerminal": true,
  "enableFileManager": true,
  "enableTunnel": true,
  "tags": ["production", "web"],
  "jumpHosts": [],
  "tunnelConnections": [],
  "quickActions": []
}
```
```

--------------------------------

### Send Input / Resize

Source: https://context7.com/termix-ssh/termix/llms.txt

Send keyboard input to the SSH stream or notify the PTY of terminal resize events.

```APIDOC
## Send Input / Resize

### Description
Send keyboard input to the SSH stream or notify the PTY of terminal resize events.

### Client WebSocket Messages

#### `input`
- **Purpose**: Send keyboard input to the SSH stream.
- **Example**: `ws.send(JSON.stringify({ type: 'input', data: 'ls -la\r' }));`

#### `resize`
- **Purpose**: Notify PTY of terminal resize.
- **Example**: `ws.send(JSON.stringify({ type: 'resize', data: { cols: 200, rows: 48 } }));`
```

--------------------------------

### Run Termix Container with Docker

Source: https://github.com/termix-ssh/termix/wiki/Docker

Launches the Termix container in detached mode, mapping ports, mounting volumes, and setting environment variables. Ensure the SALT is replaced with a secure value.

```bash
docker run -d \
  --name termix \
  --restart unless-stopped \
  -p 8080:8080 \
  -v termix-data:/app/data \
  -e SALT="replace_me" \
  -e PORT=8080 \
  ghcr.io/lukegus/termix:latest
```

--------------------------------

### ConnectToHostData Interface Definition

Source: https://context7.com/termix-ssh/termix/llms.txt

Defines the structure for connection data, including host configuration, terminal settings, and initial path or command execution.

```typescript
interface ConnectToHostData {
  cols: number;
  rows: number;
  hostConfig: {
    id: number;
    instanceId?: string;          // Tab instance identifier
    ip: string;
    port: number;
    username: string;
    password?: string;
    key?: string;                 // PEM-encoded private key
    keyPassword?: string;
    keyType?: string;
    authType?: 'password' | 'key' | 'none' | 'opkssh';
    credentialId?: number;
    userId?: string;
    forceKeyboardInteractive?: boolean;
    jumpHosts?: Array<{ hostId: number }>;
    useSocks5?: boolean;
    socks5Host?: string;
    socks5Port?: number;
    socks5Username?: string;
    socks5Password?: string;
    socks5ProxyChain?: ProxyNode[];
    portKnockSequence?: Array<{ 
      port: number;
      protocol?: 'tcp' | 'udp';
      delay?: number;
    }>;
    terminalConfig?: {
      keepaliveInterval?: number;   // ms, default 30000
      keepaliveCountMax?: number;   // default 3
      autoTmux?: boolean;
      [key: string]: unknown;
    };
  };
  initialPath?: string;           // cd to this path on connect
  executeCommand?: string;        // run this command after shell opens
}
```

--------------------------------

### Create Docker Volume for Termix Data

Source: https://github.com/termix-ssh/termix/wiki/Docker

Use this command to create a persistent volume for Termix data before running the container.

```bash
docker volume create termix-data
```

--------------------------------

### Commit Changes

Source: https://github.com/termix-ssh/termix/blob/main/CONTRIBUTING.md

Use this command to commit your changes with a descriptive message.

```sh
git commit -m "Feature request my new feature"
```

--------------------------------

### Create SSH Credential

Source: https://context7.com/termix-ssh/termix/llms.txt

Use this endpoint to create a reusable SSH credential set. Supports key-based authentication with optional passphrase and key type specification.

```bash
curl -b cookies.txt -X POST http://localhost:8080/credentials \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Key", "description": "Shared deploy key for prod servers", "authType": "key", "username": "deploy", "key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----", "keyPassword": "optional-passphrase", "keyType": "ssh-ed25519", "tags": ["production"] }'
```

--------------------------------

### Admin Operations for User Management

Source: https://context7.com/termix-ssh/termix/llms.txt

A collection of administrative endpoints for managing users. Includes listing users, granting/revoking admin rights, deleting users, and toggling various system settings like registration, password login, log level, and session timeout. Requires admin privileges and cookie authentication.

```bash
# List all users
curl -b cookies.txt http://localhost:8080/users/list

# Grant admin rights
curl -b cookies.txt -X POST http://localhost:8080/users/make-admin \
  -H "Content-Type: application/json" \
  -d '{"userId": "usr_def456"}'

# Revoke admin rights
curl -b cookies.txt -X POST http://localhost:8080/users/remove-admin \
  -H "Content-Type: application/json" \
  -d '{"userId": "usr_def456"}'

# Delete a user (admin)
curl -b cookies.txt -X DELETE http://localhost:8080/users/delete-user \
  -H "Content-Type: application/json" \
  -d '{"userId": "usr_def456"}'

# Toggle open registration
curl -b cookies.txt -X PATCH http://localhost:8080/users/registration-allowed \
  -H "Content-Type: application/json" \
  -d '{"allowed": false}'

# Toggle password login
curl -b cookies.txt -X PATCH http://localhost:8080/users/password-login-allowed \
  -H "Content-Type: application/json" \
  -d '{"allowed": true}'

# Set log level
curl -b cookies.txt -X PATCH http://localhost:8080/users/log-level \
  -H "Content-Type: application/json" \
  -d '{"level": "debug"}'

# Set session timeout (seconds)
curl -b cookies.txt -X PATCH http://localhost:8080/users/session-timeout \
  -H "Content-Type: application/json" \
  -d '{"timeout": 3600}'

# Database health check
curl -b cookies.txt http://localhost:8080/users/db-health
```

--------------------------------

### Retrieve current user profile

Source: https://context7.com/termix-ssh/termix/llms.txt

Fetches the profile information for the currently logged-in user.

```bash
curl -b cookies.txt http://localhost:8080/users/me
```

--------------------------------

### Clone the Termix Repository

Source: https://github.com/termix-ssh/termix/blob/main/CONTRIBUTING.md

Use this command to clone the Termix project repository to your local machine.

```sh
git clone https://github.com/Termix-SSH/Termix
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/termix-ssh/termix/blob/main/CONTRIBUTING.md

After committing, push your changes to your forked repository.

```sh
git push origin feature/my-feature-request
```

--------------------------------

### Complete TOTP verification for login

Source: https://context7.com/termix-ssh/termix/llms.txt

Finalizes the login process after TOTP has been initiated. Requires the temporary token and the TOTP code.

```bash
curl -c cookies.txt -X POST http://localhost:8080/users/totp/verify-login \
  -H "Content-Type: application/json" \
  -d '{"temp_token": "<temp_token>", "totp_code": "123456", "rememberMe": false}'
```

--------------------------------

### Docker Compose Configuration for Termix

Source: https://github.com/termix-ssh/termix/wiki/Docker

Defines the Termix service, image, ports, volumes, and environment variables for deployment via Docker Compose. Remember to replace the placeholder SALT.

```yaml
services:
  termix:
    image: ghcr.io/lukegus/termix:latest
    container_name: termix
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - termix-data:/app/data
    environment:
      # Generate random salt here https://www.lastpass.com/features/password-generator (max 32 characters, include all characters for settings)
      SALT: "replace_me"
      PORT: "8080"

volumes:
  termix-data:
    driver: local
```

--------------------------------

### Create Credential

Source: https://context7.com/termix-ssh/termix/llms.txt

Creates a new reusable SSH credential set. These credentials can be shared across multiple hosts.

```APIDOC
## POST /credentials

### Description
Creates a new SSH credential set, which can include private keys and associated metadata, for reuse across different hosts.

### Method
POST

### Endpoint
/credentials

### Headers
- **Content-Type**: application/json

### Request Body
- **name** (string) - Required - The name of the credential set.
- **description** (string) - Optional - A description for the credential set.
- **authType** (string) - Required - The authentication type, e.g., 'key' or 'password'.
- **username** (string) - Required - The username for the SSH connection.
- **key** (string) - Optional - The private SSH key content (PEM format).
- **keyPassword** (string) - Optional - The passphrase for the private key, if any.
- **keyType** (string) - Optional - The type of the SSH key (e.g., 'ssh-ed25519', 'ssh-rsa').
- **tags** (array of strings) - Optional - Tags for categorizing the credential.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:8080/credentials \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "Production Key",
    "description": "Shared deploy key for prod servers",
    "authType": "key",
    "username": "deploy",
    "key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
    "keyPassword": "optional-passphrase",
    "keyType": "ssh-ed25519",
    "tags": ["production"]
  }'
```
```

--------------------------------

### OIDC / SSO Management

Source: https://context7.com/termix-ssh/termix/llms.txt

Manages OpenID Connect (OIDC) and Single Sign-On (SSO) configurations and linking.

```APIDOC
## OIDC / SSO Management

### Store OIDC Provider Config
#### Description
Stores the configuration for an OIDC provider. This operation is typically for administrators.

#### Method
POST

#### Endpoint
/users/oidc-config

#### Parameters
##### Request Body
- **issuer** (string) - Required - The OIDC issuer URL.
- **clientId** (string) - Required - The client ID obtained from the OIDC provider.
- **clientSecret** (string) - Required - The client secret obtained from the OIDC provider.
- **redirectUri** (string) - Required - The redirect URI registered with the OIDC provider.

### Get OIDC Authorization URL
#### Description
Retrieves the OIDC authorization URL. Users should be redirected to this URL to initiate the SSO flow.

#### Method
GET

#### Endpoint
/users/oidc/authorize

#### Response
##### Success Response (200)
- **url** (string) - The OIDC authorization URL.

### Link OIDC to Password Account
#### Description
Links an OIDC identity to an existing password-based account.

#### Method
POST

#### Endpoint
/users/link-oidc-to-password

#### Parameters
##### Request Body
- **password** (string) - Required - The user's current password for verification.
```

--------------------------------

### Alerts API

Source: https://context7.com/termix-ssh/termix/llms.txt

API for managing system alerts based on host metrics.

```APIDOC
## POST /alerts

### Description
Creates a new alert configuration.

### Method
POST

### Endpoint
/alerts

### Parameters
#### Request Body
- **hostId** (number) - Required - The ID of the host to monitor.
- **metric** (string) - Required - The metric to monitor (e.g., 'cpu', 'memory').
- **threshold** (number) - Required - The threshold value for the metric.
- **condition** (string) - Required - The condition for the alert (e.g., 'gt' for greater than, 'lt' for less than).
```

```APIDOC
## GET /alerts

### Description
Retrieves a list of all configured alerts.

### Method
GET

### Endpoint
/alerts
```

--------------------------------

### Check User Data Status

Source: https://context7.com/termix-ssh/termix/llms.txt

Use this endpoint to check if user data is unlocked. Requires authentication via cookies.

```bash
curl -b cookies.txt http://localhost:8080/users/data-status
```

--------------------------------

### Tmux Integration

Source: https://context7.com/termix-ssh/termix/llms.txt

Manage tmux sessions, either automatically or manually.

```APIDOC
## Tmux Integration

### Description
Manage tmux sessions. When `terminalConfig.autoTmux` is true, Termix automatically detects and attaches to tmux sessions. Manual management is also supported.

### Client WebSocket Messages

#### `tmux_attach`
- **Purpose**: Attach to or create a tmux session.
- **Data Fields**:
  - `sessionName` (string) - Optional - The name of the tmux session to attach to. If omitted, a new session is created.
- **Examples**:
  - Attach to an existing session: `ws.send(JSON.stringify({ type: 'tmux_attach', data: { sessionName: 'main' } }));`
  - Create a new session: `ws.send(JSON.stringify({ type: 'tmux_attach', data: {} }));`
```

--------------------------------

### Snippets API: List and Reorder Snippets

Source: https://context7.com/termix-ssh/termix/llms.txt

Lists existing snippets or reorders them by providing an array of IDs in the desired sequence.

```bash
# List snippets
curl -b cookies.txt http://localhost:8080/snippets

# Reorder snippets
curl -b cookies.txt -X POST http://localhost:8080/snippets/reorder \
  -H "Content-Type: application/json" \
  -d '{"ids": [3, 1, 2]}'
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/termix-ssh/termix/blob/main/CONTRIBUTING.md

Before making changes, create a new branch for your feature using this Git command.

```sh
git checkout -b feature/my-new-feature
```

--------------------------------

### Port Knocking Configuration

Source: https://context7.com/termix-ssh/termix/llms.txt

Port knocking sequences are configured per-host in 'hostConfig.portKnockSequence'. This configuration is executed automatically by the backend before the SSH handshake and requires no client-side action.

```typescript
// Configured in hostConfig.portKnockSequence:
portKnockSequence: [
  { port: 1234, protocol: 'tcp', delay: 200 },
  { port: 5678, protocol: 'udp', delay: 100 },
  { port: 9012, protocol: 'tcp', delay: 150 }
]
```

--------------------------------

### Admin Operations

Source: https://context7.com/termix-ssh/termix/llms.txt

Provides administrative functions for managing users and system settings.

```APIDOC
## Admin Operations

### List All Users
#### Description
Retrieves a list of all users in the system.

#### Method
GET

#### Endpoint
/users/list

### Grant Admin Rights
#### Description
Grants administrative privileges to a specific user.

#### Method
POST

#### Endpoint
/users/make-admin

#### Parameters
##### Request Body
- **userId** (string) - Required - The ID of the user to grant admin rights to.

### Revoke Admin Rights
#### Description
Revokes administrative privileges from a specific user.

#### Method
POST

#### Endpoint
/users/remove-admin

#### Parameters
##### Request Body
- **userId** (string) - Required - The ID of the user to revoke admin rights from.

### Delete User
#### Description
Deletes a user from the system.

#### Method
DELETE

#### Endpoint
/users/delete-user

#### Parameters
##### Request Body
- **userId** (string) - Required - The ID of the user to delete.

### Toggle Open Registration
#### Description
Enables or disables open registration for new users.

#### Method
PATCH

#### Endpoint
/users/registration-allowed

#### Parameters
##### Request Body
- **allowed** (boolean) - Required - Set to `true` to allow registration, `false` to disallow.

### Toggle Password Login
#### Description
Enables or disables password-based login for users.

#### Method
PATCH

#### Endpoint
/users/password-login-allowed

#### Parameters
##### Request Body
- **allowed** (boolean) - Required - Set to `true` to allow password login, `false` to disallow.

### Set Log Level
#### Description
Sets the logging level for the system.

#### Method
PATCH

#### Endpoint
/users/log-level

#### Parameters
##### Request Body
- **level** (string) - Required - The desired log level (e.g., "debug", "info", "warn", "error").

### Set Session Timeout
#### Description
Sets the session timeout duration in seconds.

#### Method
PATCH

#### Endpoint
/users/session-timeout

#### Parameters
##### Request Body
- **timeout** (integer) - Required - The session timeout duration in seconds.

### Database Health Check
#### Description
Performs a health check on the system's database connection.

#### Method
GET

#### Endpoint
/users/db-health
```

--------------------------------

### Password Reset Flow

Source: https://context7.com/termix-ssh/termix/llms.txt

Handles the password reset process, including initiation, verification, and completion.

```APIDOC
## Password Reset Flow

### Initiate Reset
#### Description
Initiates the password reset process by sending a reset code to the user.

#### Method
POST

#### Endpoint
/users/initiate-reset

#### Parameters
##### Request Body
- **username** (string) - Required - The username for which to initiate the reset.

### Verify Reset Code
#### Description
Verifies the reset code sent to the user.

#### Method
POST

#### Endpoint
/users/verify-reset-code

#### Parameters
##### Request Body
- **username** (string) - Required - The username.
- **code** (string) - Required - The reset code received.

### Complete Reset
#### Description
Completes the password reset process by setting a new password.

#### Method
POST

#### Endpoint
/users/complete-reset

#### Parameters
##### Request Body
- **username** (string) - Required - The username.
- **code** (string) - Required - The reset code.
- **newPassword** (string) - Required - The new password to set.
```

--------------------------------

### Network Topology API: Retrieve Network Map Data

Source: https://context7.com/termix-ssh/termix/llms.txt

Retrieves the network map data, which is backed by Cytoscape.js on the frontend.

```bash
curl -b cookies.txt http://localhost:8080/network-topology
```

--------------------------------

### Snippets API

Source: https://context7.com/termix-ssh/termix/llms.txt

API for managing reusable shell snippets.

```APIDOC
## POST /snippets

### Description
Creates a new reusable shell snippet.

### Method
POST

### Endpoint
/snippets

### Parameters
#### Request Body
- **name** (string) - Required - The name of the snippet.
- **command** (string) - Required - The shell command associated with the snippet.
- **description** (string) - Optional - A brief description of the snippet.
```

```APIDOC
## GET /snippets

### Description
Retrieves a list of all available snippets.

### Method
GET

### Endpoint
/snippets
```

```APIDOC
## POST /snippets/reorder

### Description
Reorders the existing snippets based on the provided IDs.

### Method
POST

### Endpoint
/snippets/reorder

### Parameters
#### Request Body
- **ids** (array of numbers) - Required - An array of snippet IDs in the desired order.
```

--------------------------------

### Password login

Source: https://context7.com/termix-ssh/termix/llms.txt

Authenticates a user using their username and password. Returns a JWT cookie for subsequent requests. May require TOTP verification.

```APIDOC
## POST /users/login

### Description
Authenticates a user with their username and password. If Multi-Factor Authentication (MFA) like TOTP is enabled, a temporary token is returned, requiring further verification.

### Method
POST

### Endpoint
/users/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.
- **rememberMe** (boolean) - Optional - Whether to keep the user logged in.

### Request Example
```json
{
  "username": "alice",
  "password": "S3cur3P@ss!",
  "rememberMe": false
}
```

### Response
#### Success Response (200) - No MFA
- **message** (string) - Confirmation message.
- **userId** (string) - The user's unique identifier.
- **username** (string) - The logged-in username.
- **isAdmin** (boolean) - Indicates if the user has administrator privileges.

#### Success Response (200) - TOTP Required
- **requiresTOTP** (boolean) - True if TOTP verification is needed.
- **temp_token** (string) - A short-lived token for completing TOTP verification.
```

--------------------------------

### Resize PTY via WebSocket

Source: https://context7.com/termix-ssh/termix/llms.txt

Send the 'resize' message to notify the Pseudo-Terminal (PTY) of terminal size changes. Provide the new dimensions in columns and rows.

```javascript
ws.send(JSON.stringify({ type: 'resize', data: { cols: 200, rows: 48 } }));
```

--------------------------------

### SimpleDBOps: Audited Database Operations

Source: https://context7.com/termix-ssh/termix/llms.txt

Provides audited database operations. The select method wraps Drizzle queries to include audit context, requiring the database object, audit context, and user ID.

```typescript
import { SimpleDBOps } from './utils/simple-db-ops.js';

// select() wraps Drizzle queries with audit context
const results = await SimpleDBOps.select(
  db.select().from(hosts).where(eq(hosts.userId, userId)),
  'ssh_data',
  userId
);
```

--------------------------------

### Session Management

Source: https://context7.com/termix-ssh/termix/llms.txt

Manages user sessions, including listing and revoking them.

```APIDOC
## Session Management

### List Active Sessions
#### Description
Lists all active sessions for the current user.

#### Method
GET

#### Endpoint
/users/sessions

### Revoke Specific Session
#### Description
Revokes a specific user session.

#### Method
DELETE

#### Endpoint
/users/sessions/{sessionId}

#### Parameters
##### Path Parameters
- **sessionId** (string) - Required - The ID of the session to revoke.

### Revoke All Sessions
#### Description
Revokes all active sessions for the current user.

#### Method
POST

#### Endpoint
/users/sessions/revoke-all
```

--------------------------------

### Port Knocking

Source: https://context7.com/termix-ssh/termix/llms.txt

Port knocking is configured per-host and executed transparently by the backend before the SSH handshake. No client-side action is required.

```APIDOC
## Port Knocking

### Description
Port knocking is configured per-host and executed transparently by the backend before the SSH handshake. No client-side action is required.

### Host Configuration Example

```typescript
// Configured in hostConfig.portKnockSequence:
portKnockSequence: [
  { port: 1234, protocol: 'tcp', delay: 200 },
  { port: 5678, protocol: 'udp', delay: 100 },
  { port: 9012, protocol: 'tcp', delay: 150 }
]
```
```

--------------------------------

### RBAC API: Assign Role to User

Source: https://context7.com/termix-ssh/termix/llms.txt

Assigns a role to a user via the RBAC API. Requires admin privileges and sends user ID and role in JSON format.

```bash
# (admin) assign a role to a user
curl -b cookies.txt -X POST http://localhost:8080/rbac/assign \
  -H "Content-Type: application/json" \
  -d '{"userId": "usr_def456", "role": "viewer"}'
```

--------------------------------

### Generate SSH Key Pair

Source: https://context7.com/termix-ssh/termix/llms.txt

Generates a new SSH key pair (private and public keys) via the API.

```APIDOC
## POST /credentials/generate-key

### Description
Generates a new SSH key pair programmatically. You can specify the key type and, for RSA keys, the key size.

### Method
POST

### Endpoint
/credentials/generate-key

### Headers
- **Content-Type**: application/json

### Request Body
- **keyType** (string) - Required - The type of SSH key to generate (e.g., 'ssh-ed25519', 'ssh-rsa').
- **keySize** (integer) - Optional - The size of the key in bits, applicable for 'ssh-rsa' type (e.g., 4096).

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:8080/credentials/generate-key \
  -H "Content-Type: application/json" \
  -d '{"keyType": "ssh-ed25519"}'
# or for RSA:
# -d '{"keyType": "ssh-rsa", "keySize": 4096}'
```

### Response
#### Success Response (200)
Returns the generated private and public keys.

### Response Example
```json
{
  "success": true,
  "privateKey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
  "publicKey": "ssh-ed25519 AAAA..."
}
```
```

--------------------------------

### Change User Password

Source: https://context7.com/termix-ssh/termix/llms.txt

Allows users to change their password. Requires current and new passwords. Authentication via cookies is necessary.

```bash
curl -b cookies.txt -X POST http://localhost:8080/users/change-password \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "S3cur3P@ss!", "newPassword": "N3wP@ss!"}'
```

--------------------------------

### Network Topology API

Source: https://context7.com/termix-ssh/termix/llms.txt

API for retrieving network map data.

```APIDOC
## GET /network-topology

### Description
Retrieves the network map data, typically used for visualization.

### Method
GET

### Endpoint
/network-topology
```

--------------------------------

### Check Data Status

Source: https://context7.com/termix-ssh/termix/llms.txt

Checks if user data is unlocked.

```APIDOC
## GET /users/data-status

### Description
Checks whether user data is unlocked.

### Method
GET

### Endpoint
/users/data-status

### Response
#### Success Response (200)
- **unlocked** (boolean) - Indicates if the data is unlocked.
```

--------------------------------

### Send Keyboard Input via WebSocket

Source: https://context7.com/termix-ssh/termix/llms.txt

Use the 'input' message type to send keyboard input to the SSH stream. Ensure to include the carriage return '\r' for newlines.

```javascript
ws.send(JSON.stringify({ type: 'input', data: 'ls -la\r' }));
```

--------------------------------

### Password Reset Flow

Source: https://context7.com/termix-ssh/termix/llms.txt

A three-step process to reset a user's password. It involves initiating the reset, verifying a code, and finally setting a new password. Each step requires specific JSON payloads.

```bash
# 1. Initiate reset (sends reset code)
curl -X POST http://localhost:8080/users/initiate-reset \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'

# 2. Verify the reset code
curl -X POST http://localhost:8080/users/verify-reset-code \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "code": "ABC123"}'

# 3. Set the new password
curl -X POST http://localhost:8080/users/complete-reset \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "code": "ABC123", "newPassword": "R3s3tP@ss!"}'
```

--------------------------------

### Manage tmux Sessions via WebSocket

Source: https://context7.com/termix-ssh/termix/llms.txt

Integrate with tmux using the 'tmux_attach' message. Attach to an existing session by providing its 'sessionName', or create a new one by omitting 'sessionName'.

```javascript
ws.send(JSON.stringify({
  type: 'tmux_attach',
  data: { sessionName: 'main' }
}));
```

```javascript
ws.send(JSON.stringify({
  type: 'tmux_attach',
  data: {}
}));
```

--------------------------------

### Change Password

Source: https://context7.com/termix-ssh/termix/llms.txt

Allows a user to change their password.

```APIDOC
## POST /users/change-password

### Description
Changes the user's password.

### Method
POST

### Endpoint
/users/change-password

### Parameters
#### Request Body
- **currentPassword** (string) - Required - The user's current password.
- **newPassword** (string) - Required - The user's new password.
```

--------------------------------

### Session Management Operations

Source: https://context7.com/termix-ssh/termix/llms.txt

Endpoints for managing user sessions. Includes listing active sessions, revoking a specific session, and revoking all sessions. Requires cookie authentication.

```bash
# List active sessions
curl -b cookies.txt http://localhost:8080/users/sessions

# Revoke a specific session
curl -b cookies.txt -X DELETE http://localhost:8080/users/sessions/sess_xyz789

# Revoke all sessions
curl -b cookies.txt -X POST http://localhost:8080/users/sessions/revoke-all
```