Configuration file

xPort reads a YAML configuration file, by default at ~/.config/xport/config.yaml (respects XDG_CONFIG_HOME). A missing file is not an error — the hosted service works out of the box, built-in defaults apply. xport config export prints the effective configuration (all defaults merged with your file and environment) as YAML — redirect it to the config path to get a starting point for customization.

Resolution order, later entries win:

1. Built-in defaults
2. Configuration file
3. Environment variables (XPORT_*)
4. CLI flags

Example

relay:
  url: "https://relay.xport.host"
  region: eu

update:
  feed_url: ""

logging:
  level: info

auth:
  web_url: "https://app.xport.dev"
  client_id: "xport-cli"

share:
  branding:
    name: ""
    logo: ""
    accent: ""

tunnel:
  name: ""
  domain: ""
  policy_file: ""
  expires: ""
  password: ""
  qr: false
  copy: false

receive:
  message: ""
  accept: ""
  max_filesize: ""

endpoints:
  demo:
    port: 3000
  db:
    mode: tcp
    target: "localhost:5432"
    policy_file: ""

endpoints holds named definitions for xport start; the endpoint name becomes the session name.

relay

Key	Default	Description
relay.url	https://relay.xport.host	URL of the relay — fresh installs use the hosted relay with no config file at all. Point it at your own relay, e.g. http://localhost:8080, for self-hosting. Explicitly blanking it makes share commands fail with a hint.
relay.region	eu	Preferred relay region (eu, us, ap). Ignored when relay.url is set.
relay.token	(empty)	Bearer token for relays that require authentication. Never printed by xport config export.

update

Key	Default	Description
update.feed_url	https://releases.xport.dev/version.json	Signed release manifest (version.json) used by xport update. Override for mirrors or tests.

auth

OAuth server used by xport login. The defaults target the hosted service; self-hosters point these at their own account server.

Key	Default	Description
auth.web_url	https://app.xport.dev	Base URL of the account website
auth.client_id	xport-cli	OAuth public client

logging

Key	Default	Description
logging.level	info	Log level: debug, info, warn, error.

share

Defaults for share pages. See Branded share pages.

Key	Default	Description
share.branding.name	(empty)	Brand name in the share page header.
share.branding.logo	(empty)	https URL of a logo image (28 px height). Overrides account branding.
share.branding.accent	(empty)	Accent color: #rrggbb hex or oklch(...). Overrides account branding.

tunnel

Defaults for tunnel sessions (see xport <port>). Every value can be overridden per invocation with the matching CLI flag — flags win over configuration.

Key	Default	Description
tunnel.name	(empty)	Custom name for the public URL (flag: --name)
tunnel.domain	(empty)	Verified custom domain, e.g. share.acme.com (flag: --domain, see BYOD)
tunnel.policy_file	(empty)	Traffic policy file attached to every share (flag: --policy-file, see Traffic policies)
tunnel.expires	(empty)	Session lifetime, e.g. 30m, 2h (flag: --expires)
tunnel.password	(empty)	Password-protects the public URL (flag: --password)
tunnel.qr	false	Print a terminal QR code for the public URL (flag: --qr)
tunnel.copy	false	Copy the public URL to the system clipboard (flag: --copy)

Environment variables

Every key maps to an environment variable: uppercase, XPORT_ prefix, dots become underscores.

Variable	Overrides
XPORT_RELAY_URL	relay.url
XPORT_RELAY_REGION	relay.region
XPORT_RELAY_TOKEN	relay.token
XPORT_UPDATE_FEED_URL	update.feed_url
XPORT_AUTH_WEB_URL	auth.web_url
XPORT_AUTH_CLIENT_ID	auth.client_id
XPORT_TUNNEL_NAME	tunnel.name
XPORT_TUNNEL_DOMAIN	tunnel.domain
XPORT_TUNNEL_POLICY_FILE	tunnel.policy_file
XPORT_TUNNEL_EXPIRES	tunnel.expires
XPORT_TUNNEL_PASSWORD	tunnel.password
XPORT_TUNNEL_QR	tunnel.qr
XPORT_TUNNEL_COPY	tunnel.copy
XPORT_RECEIVE_MESSAGE	receive.message
XPORT_RECEIVE_ACCEPT	receive.accept
XPORT_RECEIVE_MAX_FILESIZE	receive.max_filesize
XPORT_SHARE_BRANDING_NAME	share.branding.name
XPORT_SHARE_BRANDING_LOGO	share.branding.logo
XPORT_SHARE_BRANDING_ACCENT	share.branding.accent
XPORT_LOGGING_LEVEL	logging.level
XPORT_CONFIG_DIR	Directory holding config.yaml