class trame_server.core.Server(name='trame', vn_constructor=None, **options)

Server implementation for trame. This is the core object that manage client/server communication but also holds a state and controller instance. With trame a server instance should be retrieved by using

Known options:
  • log_network: False (path to log file)

  • ws_max_msg_size: 10000000 (bytes)

  • ws_heart_beat: 30

  • desktop_debug: False

  • name (str, optional (default: trame)) – A name identifier for a given server

  • **options

    Gather any keyword arguments into options

enable_module(module, **kwargs)

Expend server using a module definition which can be used to serve custom client code or assets, load/initialize resources (js, css, vue), register custom protocols and even execute custom code.

Any previously seem module will be automatically skipped.

The attributes that are getting processed in a module are the following:
  • setup(server, **kwargs): Function called first

  • scripts = [] : List all JavaScript URL that should be loaded

  • module_scripts = [] : List all JavaScript URL as type=module to load

  • styles = [] : List all CSS URL that should be loaded

  • vue_use = [‘libName’, (‘libName2’, { **options })]: List Vue plugin to load

  • state = {} : Set of variable to add to state

  • server = { data: ‘/path/on/fs’ }: Set of endpoints to server static content

  • www = ‘/path/on/fs’ : Path served as main web content

  • module – A module to enable or a dict()

  • kwargs – Any optional parameters needed for your module setup() function.

js_call(ref: str | None = None, method: str | None = None, *args)

Python call method on JS element.

  • ref (str) – ref name of the widget element

  • method (str) – name of the method that should be called

  • *args

    set of parameters needed for the function

change(*_args, **_kwargs)

Use as decorator @server.change(key1, key2, …) so the decorated function will be called like so _fn(**state) when any of the listed key name is getting modified from either client or server.



A list of variable name to monitor


Use as decorator @server.trigger(name) so the decorated function will be able to be called from the client by doing click=”trigger(name)”.


name (str) – A name to use for that trigger


Given a function this method will register a trigger and returned its name. If manually registered, the given name at the time will be returned.


The trigger name for that function

Return type:


property name

Name of server

property options

Server options provided at instantiation time

property client_type

Specify the client type. Either ‘vue2’ or ‘vue3’ for now.

property cli

argparse parser

property state

The server shared state

Return type:


property controller

The server controller

Return type:


property ui

The server VirtualNode manager

Return type:


property running

Return True if the server is currently starting or running.

property ready

Return a future that will resolve once the server is ready


Return the current server state


Register function that will be called with a wslink.ServerProtocol when the server start and is ready for registering new wslink.Protocol.


configure_protocol_fn – A function to be called later with a wslink.ServerProtocol as argument.

property protocol

Return the server root protocol

protocol_call(method, *args, **kwargs)

Call a registered protocol method

  • method (str) – Method registration name

  • *args

    Set of args to use for that method call

  • **kwargs

    Set of keyword arguments to use for that method call


transparently return what the called function returns

start(port: int | None = None, thread: bool = False, open_browser: bool = True, show_connection_info: bool = True, disable_logging: bool = False, backend: str | None = None, exec_mode: str = 'main', timeout: int | None = None, host: str | None = None, **kwargs)

Start the server by listening to the provided port or using the –port, -p command line argument. If the server is already starting or started, any further call will be skipped.

When the exec_mode=”main” or “desktop”, the method will be blocking. If exec_mode=”task”, the method will return a scheduled task. If exec_mode=”coroutine”, the method will return a coroutine which will need to be scheduled by the user.

  • port – A port number to listen to. When 0 is provided the system will use a random open port.

  • thread – If the server run in a thread which means we should disable interuption listeners

  • open_browser – Should we open the system browser with app url. Using the –server command line argument is similar to setting it to False.

  • show_connection_info – Should we print connection URL at startup?

  • disable_logging – Ask wslink to disable logging

  • backend – aiohttp by default but could be generic or tornado. This can also be set with the environment variable TRAME_BACKEND. Defaults to 'aiohttp'.

  • exec_mode – main/desktop/task/coroutine specify how the start function should work

  • timeout – How much second should we wait before automatically stopping the server when no client is connected. Setting it to 0 will disable such auto-shutdown.

  • host – The hostname used to bind the server. This can also be set with the environment variable TRAME_DEFAULT_HOST. Defaults to 'localhost'.

  • **kwargs

    Keyword arguments for capturing optional parameters for wslink server and/or desktop browser

async stop()

Coroutine for stopping the server

property port

Once started, you can retrieve the port used