Docs
Self-hosting
Usage

Usage

This section describes teleghosts executable usage in a great detail

TL;DR: teleghosts --target <your_simplex_profile_address> and check the list of caveats

USAGE
./teleghosts [--target <address>]|[--oracle <one-time-link>] [--bot-mirror]

ARGUMENTS

 -h, --help                  Print usage information
 --target <address>          Public address of SimpleX profile to connect to
 --oracle <one-time-link>    One time invitation from teleghosts oracle for OOB start-up
 --bot-mirror                Run in a bot mirroring mode. Teleghost admin and setup bots will be disabled

ENVIRONMENT

  TEGHOST_PORT               Enforce SimpleX CLI to run on specific port
  TEGHOST_KEY                Provide DB password. Teleghost setup will skip password dialogue if this is set
  TEGHOST_TOKEN              Provide Telegram token. Teleghost setup will skip TG token step if this is set

Target mode: Manually connect the SimpleX profile 

teleghosts --target <public_profile_address>

This is the command you want to use on local machine. It connects Teleghosts directly to SimpleX profile using the public profile address. A temporary Teleghosts Setup Wizard bot will connect to you to initialize or unlock the instance. This bot will ask for sensitive information like your database password and the Telegram bot token.

[TODO: Setup Wizard Image]

The Teleghost Setup Wizard works by creating a temporary database in the ./setup directory encrypted by a random key. After gathering all the required information and ensuring that teleghosts components are successfully initialized the bot and the ./setup directory get deleted.

You can use TEGHOST_KEY and TEGHOST_TOKEN to provide the database key and the Telegram token respectively. If both variables are set the Teleghosts Setup Wizard bot won’t bother you. If only one of the variables is set the Teleghosts Setup Wizard will still connect to you to ask about the missing information.

Caution

Right now the public address is not distinguished from a one time invitation link. If you use a one time invitation link and set TEGHOST_KEY and TEGHOST_TOKEN environment variables the Telegram users won’t be able to connect to you and the app won’t report any error but you should spot an error in the logs because the sxc task will crash in this case.

Oracle mode: Initialize the instance by an automated request 

teleghosts --oracle <one_time_invitation>

Warning

not yet implemented

The oracle is another SimpleX bot that provides a bunch of secret information(like the target SimpleX profile address and the Telegram bot token) required for remote teleghosts initialization by some external service.

[TODO: DRAW ORACLE INITIALIZATION DIAGRAM]

TEGHOST_TOKEN and TEGHOST_KEY environment variables are ignored in oracle mode.

Bot mirror mode: Mirror SimpleX bot to Telegram 

teleghosts --target <public_address> --bot-mirror

Notice

Right now bot mirroring is just a proof of concept

--bot-mirror flag does only 2 things in current alphas:

  1. Ensures TEGHOST_TOKEN and TEGHOST_KEY environment variables are set to so that Teleghosts Setup Wizard won’t connect to your SimpleX bot.
  2. Disables the admin task. Teleghosts admin will still connect to your bot but it will be unresponsive.

This is enough to mirror simple SimpleX bots to Telegram. Note, that --bot-mirror doesn’t enable any extra features so bot menus won’t be bridged, bot captcha prompts will be ignored, and the markdown won’t render properly on the Telegram side.

Caveats

  • Telegram stores undelivered bot messages for ~24hours before dropping them. Don’t keep teleghosts offline for longer than 24 hours to avoid message loss.

  • There is a bunch of unadressed issues that may cause a message loss. During this alpha test we expect you to monitor logs and report any message delivery issues on sight.

Setup