diff --git a/docs/02-usage/060_dashboard.md b/docs/02-usage/060_dashboard.md index 9bb6406e..3e4e3a5a 100644 --- a/docs/02-usage/060_dashboard.md +++ b/docs/02-usage/060_dashboard.md @@ -2,38 +2,80 @@ Serena comes with built-in tools for monitoring and managing the current session: -* the **web-based dashboard** (enabled by default) +* the **Serena Dashboard** (enabled by default) The dashboard provides detailed information on your Serena session, the current configuration and provides access to logs. Some settings (e.g. the current set of active programming languages) can also be directly modified through the dashboard. The dashboard is supported on all platforms. - - By default, it will be accessible at `http://localhost:24282/dashboard/index.html`, - but a higher port may be used if the default port is unavailable/multiple instances are running. - **We recommend always enabling the dashboard**. If you don't want the browser to open automatically, - you can disable it while still keeping the dashboard running in the background (see below). - -* the **GUI tool** (disabled by default) +* the **GUI Log Viewer** (disabled by default) - The GUI tool is a native application window which displays logs. - It furthermore allows you to shut down the agent and to access the dashboard's URL (if it is running). + The GUI tool is a legacy native application which displays Serena's live logs. This is mainly supported on Windows, but it may also work on Linux; macOS is unsupported. Both can be configured in Serena's [configuration](050_configuration) file (`serena_config.yml`). -If enabled, they will automatically be opened as soon as the Serena agent/MCP server is started. -For the dashboard, this can be disabled if desired (see below). -## Disabling Automatic Browser Opening +## The Serena Dashboard -If you prefer not to have the dashboard open automatically (e.g., to avoid focus stealing), you can disable it -by setting `web_dashboard_open_on_launch: False` in your `serena_config.yml` or by passing `--open-web-dashboard False` -to `start-mcp-server` CLI command. +The dashboard is a web application, which is opened via a native application wrapper on Windows and macOS, +where it will appear in the system tray. **Click on the tray icon** to open the application window. -When automatic opening is disabled, you can still access the dashboard by: +On Linux, native app support is difficult to provide, so the dashboard will be opened in your default web browser instead. + +By default, the dashboard can be accessed at `http://localhost:24282/dashboard/index.html`, +but a higher port may be used if the default port is unavailable/multiple instances are running. + +### Features + +The dashboard provides ... + * a detailed overview of + * the current Serena status and configuration (e.g. active tools, active programming languages, enabled modes and contexts, etc.) + * ongoing and past tool calls (and statistics on tool usage) + * access to Serena's live logs + * the ability to modify settings (e.g. the set of active programming languages) on the fly + * the ability to edit + * configuration files (global `serena_config.yml` and project-specific `project.yml`) + * memories of the current project + * the ability to shut down the Serena MCP server. + +### Configuring the Dashboard + +You can configure settings for the dashboard in the [global configuration file](global-config). + +In particular, you can configure + * whether the dashboard is enabled at all. + We highly recommend keeping it enabled, as it provides valuable insights into Serena's operation and allows you to adjust configuration conveniently. + * whether the dashboard window is opened automatically when Serena is started (see below). + * network settings (for cases where you might want to access the Dashboard non-locally). + +#### Dashboard Opening Behaviour + +When Serena is started, the Dashboard window is opened by default in order to make users aware of its existence. + +If you prefer not to have this happen (e.g., to avoid focus stealing), you can disable prevent it from opening +by setting `web_dashboard_open_on_launch: False` in the [global configuration file](global-config) or by passing `--open-web-dashboard False` +to the `start-mcp-server` CLI command. + +On Windows and macOS, you can conveniently open the dashboard at any time by clicking on the tray icon, so automatic +opening is not a requirement to be able to access the dashboard on these platforms. + +On Linux, access to the dashboard is more cumbersome without native app support. +Yet you may still access it by * asking the LLM to "open the Serena dashboard", which will open the dashboard in your default browser (the tool `open_dashboard` is enabled for this purpose, provided that the dashboard is active, not opened by default and the GUI tool, which can provide the URL, is not enabled) -* navigating directly to the URL (see above) +* navigating directly to the URL (see above). + +## The GUI Log Viewer + +The Serena GUI Log Viewer is a legacy application which provides access to Serena's live logs. + +Via its menu, it furthermore allows you to + * shut down the agent + * access the dashboard's URL (if it is running). + +The tool is mainly supported on Windows, but it may work on some Linux systems as well (depending on your desktop environment). + +To enable the tool, set `gui_log_window` to `true` in Serena's [global configuration file](global-config). \ No newline at end of file diff --git a/src/serena/resources/serena_config.template.yml b/src/serena/resources/serena_config.template.yml index 7ec556db..a823c743 100644 --- a/src/serena/resources/serena_config.template.yml +++ b/src/serena/resources/serena_config.template.yml @@ -29,30 +29,26 @@ line_ending: native # we have to live with this limitation for now. gui_log_window: False -# whether to open the Serena web dashboard (which will be accessible through your web browser) that -# provides access to Serena's configuration and state as well as the current session logs. -# The web dashboard is supported on all platforms. -# We strongly recommend to always enable this option, since the dashboard provides important information -# about the current state of Serena, including the configuration, the logs and tool usage statistics. -# If you don't want the browser window to pop up automatically, set the `web_dashboard_open_on_launch` to False -# (either here or through the corresponding flag in the `start-mcp-server` CLI command). -# You can then open the dashboard by asking your agent to do so (e.g., by saying "open the dashboard"), Serena provides -# a tool for this. +# whether to start the Serena Dashboard, which provides detailed information on your Serena session, +# the current configuration and furthermore allows some settings to be conveniently modified on the fly. +# We strongly recommend to always enable this option! +# If you want to prevent the Dashboard window from being opened on launch, +# set `web_dashboard_open_on_launch` to false (see below). # Further information: https://oraios.github.io/serena/02-usage/060_dashboard.html web_dashboard: True -# the address the web dashboard will listen on (bind address). -web_dashboard_listen_address: 127.0.0.1 - -# whether to open a browser window with the web dashboard when Serena starts (provided that web_dashboard -# is enabled). See also the web_dashboard option. -# If set to false, you can still open the dashboard manually by +# whether to open the Dashboard window/browser tab when Serena starts (provided that web_dashboard is enabled). +# If set to false, you can still open the dashboard manually by clicking on the Serena icon in your system +# tray on Windows and macOS. On Linux, there is no system tray support, so you can only open the dashboard by # a) telling the LLM to "open the dashboard" (provided that the open_dashboard tool is enabled) or by # b) manually navigating to http://localhost:24282/dashboard/ in your web browser (actual port # may be higher if you have multiple instances running; try ports 24283, 24284, etc.) # See also: https://oraios.github.io/serena/02-usage/060_dashboard.html web_dashboard_open_on_launch: True +# the address the web dashboard will listen on (bind address). +web_dashboard_listen_address: 127.0.0.1 + # address where JetBrains plugin servers are running (only relevant when using the JetBrains language backend) jetbrains_plugin_server_address: 127.0.0.1