Serve Textual TUI apps over SSH. Import your Textual app, hand it to serve, and anyone with an SSH client can connect and use the app in their terminal — no installation required on their end.
Each SSH session gets a fresh app instance and driver on one shared asyncio event loop. That keeps per-user input and screen state separate without re-importing Textual or starting a thread/process for every connection.
# run.py
from textish import serve
from myapp import MyApp # your Textual App, in an importable module
serve(MyApp, port=2222)python run.py
# then, from another terminal:
ssh localhost -p 2222
Textual talks to the outside world through a Driver. The stock drivers assume a real terminal: they read sys.stdin, write sys.stdout, set termios, and install signal handlers. textish replaces that with an SSHDriver whose terminal is one AsyncSSH channel.
For each interactive SSH session:
- A fresh app instance is constructed from the class, factory, or import reference.
- A session-specific
SSHDriverwrites rendered bytes directly to its SSH channel and parses only that client's input. - All sessions share the server's modules and asyncio loop. There are no per-session threads, subprocesses, polling loops, or cross-interpreter queues.
- Startup concurrency is bounded so a burst of new clients does not monopolize the event loop. Slow clients are disconnected when their SSH output buffer reaches the safety limit.
This is the same idea as wish (Charmbracelet's SSH app framework for Go): the app is imported and run in-process rather than launched as a subprocess.
textish is designed for trusted Textual applications, such as dashboards, browsers, administration tools, and controlled interactive apps—not for hosting arbitrary user-supplied Python code. Earlier subinterpreter experiments consumed substantially more memory per session, added queues and lifecycle complexity, and still did not provide a security sandbox.
The shared model keeps the useful isolation: every SSH session receives a fresh app object, driver, input stream, terminal size, and screen state. It deliberately shares imported modules, process globals, the GIL, and the asyncio event loop. This makes thousands of connections much lighter, with two requirements for the served app:
- Keep per-user mutable state on the app instance or in a store keyed by user.
- Keep handlers non-blocking and move CPU-heavy work to another process or service.
For the component design and data flow, see ARCHITECTURE.md.
Requires Python 3.12 or later.
pip install textish
Optional coloured logs and uvloop support are available as extras:
pip install "textish[color,performance]"
Pass serve your App subclass, any zero-argument factory, or a "module:attr" string. Classes and factories may be defined in the script itself. A fresh app instance is created for every session. serve blocks until interrupted and generates a host key on first run.
textish my_package.my_module:MyApp
textish my_package.my_module:MyApp --port 3000
textish my_package.my_module:MyApp --host 127.0.0.1 --port 3000 --max-connections 10
Run textish --help for all options. The main controls are --host, --port,
--host-key, --max-connections, --idle-timeout, and --authorized-keys.
Use --log-level DEBUG (or -v) for detailed server logs.
from textish import serve
from myapp import MyApp
serve(MyApp, port=2222, max_connections=10)serve blocks and runs its own event loop. If you are embedding textish in a program that already has a running loop, build an AppConfig and use the async entry point instead:
from textish import AppConfig, serve_async
await serve_async(AppConfig(app_ref="myapp:MyApp", port=2222))The async entry point generates the host key when needed, just like serve.
serve generates ~/.ssh/textish_host_key with private permissions on first run. To use a specific key, pass a path; it is generated there if missing:
serve(MyApp, port=2222, host_key_path="/etc/textish/ssh_host_key")Or generate one yourself:
ssh-keygen -t ed25519 -f ~/.ssh/textish_host_key -N ""
By default, textish listens only on 127.0.0.1 and allows connections without authentication. If you bind to a non-loopback interface, configure authentication; textish logs a warning when a public bind has no authentication callback.
ALLOWED_KEYS = {"ssh-ed25519 AAAAC3Nza..."}
def auth(username: str, public_key: str) -> bool:
return public_key in ALLOWED_KEYS
serve(MyApp, port=2222, auth=auth)The function receives the username and the client's public key in OpenSSH format. It may also be async. See also authorized_keys() for reading an OpenSSH authorized_keys file.
The examples/ directory has two runnable apps:
examples/main.py— a small Wordle game (python examples/main.py).examples/serve_docbrowser.py— a document browser with a clickable sidebar and a long, scrollable Markdown pane, showing text rendering, scrolling, and mouse interaction (python examples/serve_docbrowser.py). Use a large terminal window.
Both start a server on 127.0.0.1:2222; connect with ssh -p 2222 localhost.
Sessions share imported code but keep independent app and widget state. Memory use therefore depends mainly on the app tree, terminal size, and data retained for each user.
All apps share one event loop and GIL. Keep event handlers short and non-blocking,
use async I/O, and move blocking work to a Textual worker or
asyncio.to_thread(). CPU-heavy work should use a process pool or external
service. A blocking handler can delay every connected user.
AsyncSSH already advertises delayed zlib@openssh.com compression. Clients which benefit from compression can request it with ssh -C. textish does not force compression because ANSI screen updates are often small or repetitive already, while compression adds CPU and per-connection state. Test it with your own traffic before enabling it broadly.
textish owns transport security and resource safety: SSH host keys, authentication hooks, session limits, idle timeouts, and bounded output buffering. Your app owns domain authorization and safe handling of user input—for example, deciding which records a username may view and validating values before using them in database queries or commands.
The shared interpreter is not a security boundary. Serve only trusted application code and do not use textish to execute arbitrary commands or untrusted Python. Even view-only applications must enforce which records each authenticated user may access. textish secures and limits the SSH transport; it cannot infer an application's domain permissions.
PTY required. textish only supports interactive shell sessions with a pseudo-terminal. Clients that connect without a PTY (for example, ssh host -p 2222 some-command) are rejected with an error message.
Shared event loop. Blocking or CPU-heavy app code affects all sessions.
Shared process. All sessions share one OS process. A whole-process fault (a C-extension crash, out-of-memory) affects every session, unlike a one-process-per-connection design.
Shared module state. App instances are separate, but imported modules, class variables, caches, and other process globals are shared.
Server-side standard streams. Textual's process-wide stdout/stderr capture
is disabled because concurrent apps cannot safely replace shared streams.
print() writes to the server terminal, not to an SSH client; use logging for
diagnostics and widgets for client-visible output.
Install with dev dependencies:
poetry install --with dev
Run the tests:
poetry run pytest
Lint and type-check:
poetry run ruff check .
poetry run mypy