class trame_server.core.Server(name='trame', vn_constructor=None, translator=None, parent_server=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

property change

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

property trigger

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

property trigger_name

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 root_server

Root server to start

property translator

Translator of the 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 context

The server-only context (not shared with the client).


The server context 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


Should only be needed when client corrupted its data and need the server need to send it again.



Set of key names to be send again to the client.

start(port: int | None = None, thread: bool = False, open_browser: bool | None = None, 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

property server_options

Once started, you can retrieve the server options used