.nh
.TH "UPTERM" "1" "Jan 2026" "Upterm 0.0.0+dev" "Upterm Manual"

.SH NAME
upterm-host - Host a terminal session


.SH SYNOPSIS
\fBupterm host [flags]\fP


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

.PP
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)

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


.SH OPTIONS
\fB--accept\fP[=false]
	Automatically accept client connections without prompts.

.PP
\fB--authorized-keys\fP=""
	Specify a authorize_keys file listing authorized public keys for connection.

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

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

.PP
\fB--github-user\fP=[]
	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.

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

.PP
\fB-h\fP, \fB--help\fP[=false]
	help for host

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

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

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

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

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

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

.PP
\fB--skip-host-key-check\fP[=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.

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


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


.SH EXAMPLE
.EX
  # 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

  # Use a different Uptermd server, hosting a session via WebSocket:
  upterm host --server wss://YOUR_UPTERMD_SERVER -- YOUR_COMMAND
.EE


.SH SEE ALSO
\fBupterm(1)\fP


.SH HISTORY
14-Jan-2026 Auto generated by spf13/cobra