repository·main·Indexed 23 days ago
https://github.com/textualize/textual-webA tool for publishing Textual applications and local terminals to the web with public URLs. It provides a CLI for serving apps via TOML configuration, supports account-based permanent URLs, and includes a GanglionClient for managing websocket connections and application sessions. Terminals are currently supported on macOS and Linux.
You can use Textual Web to serve your local terminal to a web browser by using the -t switch. This generates a random public URL that presents your terminal in the browser.
WARNING Don't share this with anyone you wouldn't trust to have access to your machine.
Note: Terminals currently work on macOS and Linux only. Windows support is planned for a future update.
textual-web -tThe easiest way to install Textual Web is using pipx. This will make the textual-web command available on your path.
pipx install textual-webpipx install textual-webtextual-web command. This will provide public URLs that you can access in your browser.textual-webBy default, Textual Web generates random URLs that change every time you run the application. To create permanent URLs, you must create an account.
textual-web --signupganglion.toml file.ganglion.toml file contains an [account] section with an api_key.ganglion.toml directly:textual-web --config ganglion.tomlWith an account, the generated URLs will include your account slug, ensuring they remain consistent across runs.
textual-web --signupYou can serve multiple Textual apps or terminals simultaneously by providing a configuration file via the --config flag. The configuration file uses TOML format.
To serve a Textual app, define an [app.<Name>] section with a command key specifying the command to run the app.
You can also optionally set a slug to explicitly define the text used in the URL.
[app.Calculator]
command = "python calculator.py"
slug = "calc"
[app.Dictionary]
command = "python dictionary.py"To serve a terminal, define a [terminal.<Name>] section. By default, this launches your current shell. You can specify a custom command to run a specific program (e.g., htop).
[terminal.Terminal]
[terminal.HTOP]
command = "htop"textual-web --config your_config.tomltextual-web --config serve.tomlTo see detailed internal logs for debugging, set the DEBUG environment variable to 1 when running the command.
Note: This may generate significant output and can potentially slow down your applications.
DEBUG=1 textual-web --config ganglion.tomlThe textual-web configuration is defined in a TOML file. The configuration structure consists of an account section and multiple application sections.
Applications can be defined in two ways within the TOML file:
app key: Standard applications.terminal key: Applications specifically configured to serve a terminal.Fields for an application include:
name: The name of the application.slug: A URL-friendly identifier (automatically generated if not provided).path: The directory path to the application (supports environment variable expansion).color: A color string for the application.command: The command to run the application (supports environment variable expansion).terminal: A boolean indicating if the application is a terminal session.The get_environment function allows you to retrieve a pre-defined Environment configuration object based on a name string. This is useful for switching between different deployment targets like production, development, or local development.
Available environment names are:
prod: Production settings (API: https://textual-web.io/api/, Websocket: wss://textual-web.io/app-service/)dev: Development settings (API: https://textualize-dev.io/api/, Websocket: wss://textualize-dev.io/app-service/)local: Local development settings (API: ws://127.0.0.1:8080/api/, Websocket: ws://127.0.0.1:8080/app-service/)If an invalid environment name is provided, a RuntimeError is raised.
To intercept or process data flowing between a Session and a client, you can extend SessionConnector. You can override the following asynchronous methods to handle different types of incoming data:
on_data(data: bytes): Triggered when raw bytes are received from the session.on_meta(meta: Meta): Triggered when metadata (a mapping) is received from the session.on_binary_encoded_message(payload: bytes): Triggered when binary encoded data is received from the process.on_close(): Triggered when the session is closed.The RequestDeliverChunk packet is used when the server requests a specific chunk of a file from the running application. You can create this packet using the build class method, which performs type validation on the provided attributes.
Attributes:
route_key (str): The routing identifier.delivery_key (str): The delivery identifier.chunk_size (int): The size of the chunk requested.Communication within a specific session route is handled via SessionData, RoutePing, and RoutePong.
SessionData(route_key, data): Carries the actual data for a remote app. Sent by both.RoutePing(route_key, data): A session-specific ping. Sent by server. data is a str.RoutePong(route_key, data): A session-specific pong. Sent by both. data is a str.You can dynamically add new applications to the SessionManager using the add_app method. This allows the server to recognize new commands as routable apps.
Arguments:
name: The display name of the app.command: The shell command used to run the application.slug: The URL slug used to identify the app. If left blank, a slug will be auto-generated.terminal: If True, the app will run as a TerminalSession instead of an AppSession. Note that terminal sessions are currently not supported on Windows.