{"id":5519,"library":"textual-serve","title":"Textual Serve","description":"textual-serve is an open-source project that allows you to serve and access your Textual TUI (Text-based User Interface) applications via a web browser. The Textual app runs on a machine/server under your control and communicates with the browser via a custom protocol over WebSockets. End-users interacting with the app via their browser do not have direct access to the machine the application is running on, only to the running Textual app. It effectively turns Textual TUIs into multi-user web applications. The current version is 1.1.3, and it has a regular release cadence with recent updates.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/Textualize/textual-serve","tags":["TUI","textual","web application","terminal","browser","websocket","server"],"install":[{"cmd":"pip install textual-serve","lang":"bash","label":"Install textual-serve"}],"dependencies":[{"reason":"textual-serve is designed to serve Textual applications, making Textual a core dependency for any functional use.","package":"textual","optional":false}],"imports":[{"note":"The `Server` class is nested within the `server` module inside `textual_serve`.","wrong":"from textual_serve import Server","symbol":"Server","correct":"from textual_serve.server import Server"}],"quickstart":{"code":"from textual.app import App, ComposeResult\nfrom textual.widgets import Header, Footer, Static\nfrom textual_serve.server import Server\n\nclass MinimalApp(App):\n    BINDINGS = [(\"q\", \"quit\", \"Quit\")]\n    def compose(self) -> ComposeResult:\n        yield Header()\n        yield Static(\"Hello from Textual Served!\")\n        yield Footer()\n\n    def action_quit(self) -> None:\n        self.exit()\n\n# Save the above Textual app as 'my_app.py'\n# Then run the textual-serve server programmatically:\n# Note: This will block and serve the app on http://localhost:8000\n# You can also use the command line: textual serve my_app.py\n\nif __name__ == \"__main__\":\n    # To run a Textual app directly:\n    # app = MinimalApp()\n    # app.run()\n\n    # To serve it via textual-serve\n    print(\"Starting textual-serve on http://localhost:8000...\")\n    print(\"Press Ctrl+C to stop the server.\")\n    server = Server(\"python my_app.py\", host=\"localhost\", port=8000)\n    server.serve()\n","lang":"python","description":"This quickstart demonstrates how to create a simple Textual application and then serve it using `textual-serve`. The `Server` class takes a shell command to launch your Textual app. The app will be accessible in a web browser, typically at `http://localhost:8000` by default."},"warnings":[{"fix":"Users may need to right-click and use the browser's paste option, or manually type the input. Check GitHub issues for potential workarounds or fixes.","message":"Pasting text into Textual inputs via Ctrl+V (or equivalent) in a web browser served by `textual-serve` may not work as expected if the text was copied from outside the GUI. This is a known issue.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the release notes for both `textual` and `textual-serve` before upgrading. Pin `textual` dependency versions if stability is critical.","message":"`textual-serve` relies heavily on the `textual` framework. `textual` underwent significant changes and breaking API updates frequently in its pre-1.0 versions. While `textual-serve` itself is past 1.0, ensure compatibility with the `textual` version you are using, as updates to `textual` might indirectly affect `textual-serve` applications.","severity":"breaking","affected_versions":"Prior to textual-serve v1.0.0 (indirectly via textual library updates)"},{"fix":"Thoroughly test the shell command (`python your_app.py` or `textual run your_app.py`) independently in a terminal to ensure it works before passing it to `textual_serve.server.Server`.","message":"The `Server` class expects a shell command that successfully launches a Textual application. If the command is incorrect or the Textual app fails to start, `textual-serve` will encounter a `RuntimeError` or similar issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Design Textual applications served with `textual-serve` with this isolated execution model in mind. Any host system interaction must be explicitly built into the Textual app's functionality.","message":"It's crucial to understand that `textual-serve` does not expose a raw shell in the browser. Instead, it communicates with the running Textual application via a custom WebSocket protocol. This is a security feature, but it means users cannot execute arbitrary commands on the host system.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}