UPTERM(1)

NAME
upterm-host - Host a terminal session

SYNOPSIS
upterm host [flags]

DESCRIPTION
Host a terminal session via a reverse SSH tunnel to the Upterm server.

The session links the host and client IO to a command's IO. Authentication with the Upterm server uses private keys in this order:
  1. Private key files: ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519, ~/.ssh/id_rsa
  2. SSH Agent keys
  3. Auto-generated ephemeral key (if no keys found)

To authorize client connections, use --authorized-keys to specify an authorized_keys file containing client public keys.

OPTIONS
--accept[=false]
    Automatically accept client connections without prompts.

--allow-local-tcp-forwarding[=false]
    Allow clients to use SSH local TCP forwarding (ssh -L) through the hosted session, reaching TCP destinations visible to the host.

--authorized-keys=""
    Specify a authorize_keys file listing authorized public keys for connection.

--codeberg-user=[]
    Authorize specified Codeberg users by allowing their public keys to connect.

-f, --force-command=""
    Enforce a specified command for clients to join, and link the command's input/output to the client's terminal.

--github-user=[]
    Authorize specified GitHub users by allowing their public keys to connect. Configure GitHub CLI environment variables as needed; see https://cli.github.com/manual/gh_help_environment for details.

--gitlab-user=[]
    Authorize specified GitLab users by allowing their public keys to connect.

-h, --help[=false]
    help for host

--hide-client-ip[=false]
    Hide client IP addresses from output (auto-enabled in CI environments).

--known-hosts="/build/.ssh/known_hosts"
    Specify a file containing known keys for remote hosts (required).

--no-sftp[=false]
    Disable file transfer via SFTP/SCP. By default, clients can transfer files with the same access as the terminal session.

-i, --private-key=[]
    Specify private key files for public key authentication with the upterm server (required).

-r, --read-only[=false]
    Host a read-only session, preventing client interaction. Also restricts SFTP to download-only.

--server="ssh://uptermd.upterm.dev:22"
    Specify the upterm server address (required). Supported protocols: ssh, ws, wss.

--skip-host-key-check[=false]
    Automatically accept unknown server host keys and add them to known_hosts (similar to SSH's StrictHostKeyChecking=accept-new). This bypasses host key verification for new connections.

--srht-user=[]
    Authorize specified SourceHut users by allowing their public keys to connect.

OPTIONS INHERITED FROM PARENT COMMANDS
--debug[=false]
    enable debug level logging (log file: /build/.upterm/upterm.log).

EXAMPLE
      # Host a terminal session running $SHELL, attaching client's IO to the host's:
      upterm host
      # Accept client connections automatically without prompts:
      upterm host --accept
      # Host a terminal session allowing only specified public key(s) to connect:
      upterm host --authorized-keys PATH_TO_AUTHORIZED_KEY_FILE
      # Host a session executing a custom command:
      upterm host -- docker run --rm -ti ubuntu bash
      # Host a 'tmux new -t pair-programming' session, forcing clients to join with 'tmux attach -t pair-programming':
      upterm host --force-command 'tmux attach -t pair-programming' -- tmux new -t pair-programming
      # Allow clients to use local TCP forwarding (ssh -L) through the hosted session:
      upterm host --allow-local-tcp-forwarding
      # Use a different Uptermd server, hosting a session via WebSocket:
      upterm host --server wss://YOUR_UPTERMD_SERVER -- YOUR_COMMAND

SEE ALSO
upterm(1)

HISTORY
2-Sep-2026 Auto generated by spf13/cobra