feat: filter and scope the workspace list (#318)

Until now the plugin pulled back workspaces without applying any
meaningful scope, so the list it showed was effectively the whole
deployment. There was no way to narrow it down or to deliberately choose
whose workspaces you wanted to see.

This hit administrators hardest. On a large deployment the list could be
huge, mixing together the workspaces of every user, with no quick way to
focus on a particular person, template, or state.

This change puts that choice in the user's hands. A scope selector
switches between just your own workspaces and every workspace you're
allowed to access, and the selection is remembered separately for each
deployment so it sticks the next time you connect. Alongside it, a
search box narrows the list by name, template, owner, or status,
including quoted multi-word values and a plain-text shortcut that
searches by workspace name. An explicit owner in the search always takes
precedence over the selected scope. Changing the scope or the search
reloads the list and regenerates SSH configuration to match what is
shown.

Deep links can now carry an owner as well, so a link to a workspace name
that several users share resolves to the right one instead of guessing.
When no owner is given the lookup stays unscoped, preserving the
previous behavior.

To keep the list manageable out of the box, it now defaults to showing
only your own workspaces. Anyone who relied on seeing everything can
switch the scope to all workspaces, and that preference is then
remembered per deployment.

- resolves DEVEX-372 
- resolves DEVEX-374

Author: fioan89

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - support Toolbox 3.5 provider header behavior
+- workspace list filtering that mirrors the Coder web dashboard
 
 ### Fixed
 
@@ -14,7 +15,10 @@
 ### Changed
 
 - skip the Coder TLS alternate hostname when fetching IDE metadata from JetBrains
-- notifications are now persistent popups instead of snackbars, so they survive a hidden window and no longer get dropped
+- notifications are now persistent popups instead of snackbars, so they survive a hidden window and no longer get
+  dropped
+- workspace lists now default to `My workspaces`, so users initially see only workspaces they own. Users can
+  switch to `All workspaces`, and that selection is persisted per Coder deployment hostname.
 
 ## 0.9.0 - 2026-05-14
 

README.md

@@ -76,6 +76,7 @@ jetbrains://gateway/com.coder.toolbox
   ?url=http(s)://<your-coder-deployment>
   &token=<auth-token>
   &workspace=<workspace-name>
+  &owner=<workspace-owner>
   &agent_name=<agent-name>
   &ide_product_code=<IDE-code>
   &ide_build_number=<IDE-build>
@@ -94,11 +95,16 @@ jetbrains://gateway/coder?url=http(s)://<your-coder-deployment>
 | url              | 	Your Coder deployment URL (encoded)                                                               | Yes       |
 | token            | 	Coder authentication token                                                                        | Yes       |
 | workspace        | 	Name of the Coder workspace to connect to.                                                        | Yes       |
+| owner            | 	Owner username, UUID, or `me` used to disambiguate the workspace lookup.                          | No        |
 | agent_name       | 	The name of the agent with the workspace                                                          | No        |
 | ide_product_code | 	JetBrains IDE product code (e.g., GO for GoLand, RR for Rider)                                    | No        |
 | ide_build_number | 	Specific build number or placeholder (see below) of the JetBrains IDE to install on the workspace | No        |
 | folder           | 	Absolute path to the project folder to open in the remote IDE (URL-encoded)                       | No        |
 
+When `owner` is present, the URI handler sends `owner:<owner>` as the workspace lookup query and then exact-matches the
+`workspace` value in the returned list. This lookup is independent of the workspace list filtering controls in the
+header. When `owner` is omitted, the URI handler sends no workspace lookup query.
+
 > [!NOTE]
 > If only a single agent is available, specifying an agent name is optional. However, if multiple agents exist, you must
 > provide the
@@ -442,6 +448,53 @@ When reporting issues, include HTTP logs to help diagnose:
 The Coder Settings allows users to control CLI download behavior, SSH configuration, TLS parameters, and data
 storage paths. The options can be configured from the plugin's main Workspaces page > deployment action menu > Settings.
 
+### Workspace list filtering
+
+The expandable header on the Coder Workspaces page mirrors the workspace filtering in the Coder web dashboard. The first
+row is a free-form search field; the second row holds three dropdowns: **Filters** (presets), **Template**, and
+**Status**.
+
+- The search field holds
+  a [Coder workspace filter query](https://coder.com/docs/user-guides/workspace-management#workspace-filtering)
+  and is sent to the server verbatim as the `q` parameter. The server parses and validates it.
+- The list defaults to `owner:me` (your own workspaces) on each load. Nothing is persisted between sessions.
+- The dropdowns are shortcuts that edit the search text, exactly like the dashboard:
+    - **Filters** replaces the whole query with the chosen preset: `My workspaces` (`owner:me`), `All workspaces`
+      (empty), `Running workspaces` (`status:running`), `Failed workspaces` (`status:failed`),
+      `Outdated workspaces` (`outdated:true`), `Shared workspaces` (`shared:true`), and `Dormant workspaces`
+      (`dormant:true`). When the search text matches no preset, the dropdown shows `Custom`.
+    - **Template** sets or replaces the `template:` term.
+    - **Status** sets or replaces the `status:` term.
+- The dropdowns and the search text stay in sync: editing the text updates the dropdowns, and selecting a dropdown value
+  updates the text. Because each key appears at most once, the dropdowns never produce a duplicate-key query.
+- If the server rejects the query (for example a duplicate key, or a malformed term), the validation message is shown in
+  a secondary label after the dropdowns.
+
+Examples of what is sent as the `q` parameter:
+
+| Search field              | Sent as `q`               |
+|---------------------------|---------------------------|
+| empty                     | no `q` parameter          |
+| `owner:me` (default)      | `owner:me`                |
+| `owner:me name:bobiverse` | `owner:me name:bobiverse` |
+| `template:"Heaven 3"`     | `template:"Heaven 3"`     |
+| `status:running`          | `status:running`          |
+
+The Template dropdown is populated from the deployment's templates, fetched each time the header becomes visible.
+Changing the search or a dropdown refreshes the workspace list and regenerates SSH configuration from the refreshed
+workspace
+set.
+With wildcard SSH enabled, the generated block uses the deployment wildcard host pattern. With wildcard SSH disabled,
+the generated block contains entries for the currently resolved workspace/agent pairs.
+
+SSH hostnames include the workspace owner so workspaces with the same name owned by different users remain distinct.
+With wildcard SSH enabled, the SSH config contains a deployment-wide `Host coder-jetbrains-toolbox-<host>--*` entry, and
+the plugin connects through hostnames shaped like
+`coder-jetbrains-toolbox-<host>--<owner>--<workspace>.<agent>`. With wildcard SSH disabled, the SSH config writes one
+explicit entry per resolved workspace/agent using
+`Host coder-jetbrains-toolbox--<owner>--<workspace>.<agent>--<host>`, and its proxy command targets
+`<owner>/<workspace>.<agent>`.
+
 ### CLI related settings
 
 - `Binary source` specifies the source URL or relative path from which the Coder CLI should be downloaded.
@@ -549,7 +602,7 @@ support, may trigger regeneration of SSH configurations.
    JetBrains enabled auto-approval for the plugin, so we need to ensure we continue to meet the following requirements:
     - do **not** use Kotlin experimental APIs.
     - do **not** add any lambdas, handlers, or class handles to Java runtime hooks.
-   - do **not** create threads manually (including via libraries). If you must, ensure they are properly cleaned up in
-     the plugin's `CoderRemoteProvider#close()` method.
+    - do **not** create threads manually (including via libraries). If you must, ensure they are properly cleaned up in
+      the plugin's `CoderRemoteProvider#close()` method.
     - do **not** bundle libraries that are already provided by Toolbox.
     - do **not** perform any ill-intentioned actions.

gradle.properties

@@ -1,3 +1,3 @@
-version=0.9.0
+version=0.9.1
 group=com.coder.toolbox
 name=coder-toolbox

src/main/kotlin/com/coder/toolbox/CoderRemoteProvider.kt

@@ -69,8 +69,9 @@ class CoderRemoteProvider(
     private var pollJob: Job? = null
     internal val lastEnvironments = mutableListOf<CoderRemoteEnvironment>()
 
-    private val triggerSshConfig = Channel<Boolean>(Channel.CONFLATED)
-    private val triggerProviderVisible = Channel<Boolean>(Channel.CONFLATED)
+    private val sshConfigTrigger = Channel<Boolean>(Channel.CONFLATED)
+    private val workspaceRefreshTrigger = Channel<Boolean>(Channel.CONFLATED)
+    private val providerVisibleTrigger = Channel<Boolean>(Channel.CONFLATED)
     private val dialogUi = DialogUi(context)
 
     // The REST client, if we are signed in
@@ -82,8 +83,13 @@ class CoderRemoteProvider(
 
     private val isInitialized: MutableStateFlow<Boolean> = MutableStateFlow(false)
 
-    private val coderHeaderPage = NewEnvironmentPage(context.i18n.pnotr(context.deploymentUrl.toString()))
-    private val settingsPage: CoderSettingsPage = CoderSettingsPage(context, triggerSshConfig) {
+    private val coderHeaderPage = NewEnvironmentPage(
+        context,
+        context.i18n.pnotr(context.deploymentUrl.toString()),
+        workspaceRefreshTrigger,
+        templatesProvider = { client?.templates() ?: emptyList() }
+    )
+    private val settingsPage: CoderSettingsPage = CoderSettingsPage(context, sshConfigTrigger) {
         client?.let { restClient ->
             if (context.settingsStore.useAppNameAsTitle) {
                 coderHeaderPage.setTitle(context.i18n.pnotr(restClient.appName))
@@ -170,13 +176,18 @@ class CoderRemoteProvider(
                     onTimeout(POLL_INTERVAL) {
                         context.logger.debug("workspace poller waked up by the $POLL_INTERVAL timeout")
                     }
-                    triggerSshConfig.onReceive { shouldTrigger ->
+                    sshConfigTrigger.onReceive { shouldTrigger ->
                         if (shouldTrigger) {
                             context.logger.debug("workspace poller waked up because it should reconfigure the ssh configurations")
                             cli.configSsh(lastEnvironments.map { it.asPairOfWorkspaceAndAgent() }.toSet())
                         }
                     }
-                    triggerProviderVisible.onReceive { isCoderProviderVisible ->
+                    workspaceRefreshTrigger.onReceive { shouldTrigger ->
+                        if (shouldTrigger) {
+                            context.logger.debug("workspace poller waked up to fetch workspaces from the latest header settings")
+                        }
+                    }
+                    providerVisibleTrigger.onReceive { isCoderProviderVisible ->
                         if (isCoderProviderVisible) {
                             context.logger.debug("workspace poller waked up by Coder Toolbox which is currently visible, fetching latest workspace statuses")
                         }
@@ -199,7 +210,18 @@ class CoderRemoteProvider(
         client: CoderRestClient,
         cli: CoderCLIManager,
     ): List<CoderRemoteEnvironment> {
-        return client.workspaces().flatMap { ws ->
+        val workspaces = try {
+            client.workspaces(coderHeaderPage.workspaceSearchQuery.value)
+        } catch (ex: APIResponseException) {
+            // Surface invalid search queries on the header instead of failing the whole poll.
+            if (ex.isValidationError) {
+                coderHeaderPage.reportFilterError(ex.validationMessage)
+                return emptyList()
+            }
+            throw ex
+        }
+        coderHeaderPage.reportFilterError(null)
+        return workspaces.flatMap { ws ->
             // Agents are not included in workspaces that are off
             // so fetch them separately.
             val resources = when (ws.latestBuild.status) {
@@ -329,7 +351,7 @@ class CoderRemoteProvider(
     override fun setVisible(visibility: ProviderVisibilityState) {
         if (visibility.providerVisible) {
             context.cs.launch(CoroutineName("Notify Plugin Visibility")) {
-                triggerProviderVisible.send(true)
+                providerVisibleTrigger.send(true)
             }
         }
     }
@@ -356,12 +378,14 @@ class CoderRemoteProvider(
             if (sameUrl(newUrl, client?.url)) {
                 coderHeaderPage.isBusy.update { true }
                 try {
-                    if (context.settingsStore.requiresTokenAuth) {
+                    val activeSession = if (context.settingsStore.requiresTokenAuth) {
                         newToken?.let {
                             refreshSession(newUrl, it)
-                        }
+                        } ?: (this.client!! to this.cli!!)
+                    } else {
+                        this.client!! to this.cli!!
                     }
-                    linkHandler.handle(params, newUrl, this.client!!, this.cli!!)
+                    linkHandler.handle(params, newUrl, activeSession.first, activeSession.second)
                 } finally {
                     coderHeaderPage.isBusy.update { false }
                 }
@@ -507,6 +531,8 @@ class CoderRemoteProvider(
         this.client = newRestClient
         this.cli = newCli
         lastEnvironments.forEach { it.updateClientAndCli(newRestClient, newCli) }
+        coderHeaderPage.resetFilter()
+        context.cs.launch(CoroutineName("Load Templates")) { coderHeaderPage.reloadTemplates() }
         pollJob = poll(newRestClient, newCli)
         context.logger.info("Workspace poll job with name ${pollJob.toString()} was created while handling URI")
         return newRestClient to newCli
@@ -627,6 +653,8 @@ class CoderRemoteProvider(
             context.i18n.pnotr(client.me.username)
         }
         accountDropdownField.visibility.update { true }
+        coderHeaderPage.resetFilter()
+        context.cs.launch(CoroutineName("Load Templates")) { coderHeaderPage.reloadTemplates() }
         pollJob = poll(client, cli)
         context.logger.info("Workspace poll job with name ${pollJob.toString()} was created")
     }

src/main/kotlin/com/coder/toolbox/CoderToolboxContext.kt

@@ -13,6 +13,7 @@ import com.jetbrains.toolbox.api.remoteDev.connection.ToolboxProxySettings
 import com.jetbrains.toolbox.api.remoteDev.states.EnvironmentStateColorPalette
 import com.jetbrains.toolbox.api.remoteDev.ui.EnvironmentUiPageManager
 import com.jetbrains.toolbox.api.ui.ToolboxUi
+import com.jetbrains.toolbox.api.ui.components.UiComponents
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineName
 import kotlinx.coroutines.CoroutineScope
@@ -22,6 +23,7 @@ import java.net.URL
 @Suppress("UnstableApiUsage")
 data class CoderToolboxContext(
     val ui: ToolboxUi,
+    val uiComponents: UiComponents,
     val envPageManager: EnvironmentUiPageManager,
     val envStateColorPalette: EnvironmentStateColorPalette,
     val remoteIdeOrchestrator: RemoteToolsHelper,

src/main/kotlin/com/coder/toolbox/CoderToolboxExtension.kt

@@ -18,6 +18,7 @@ import com.jetbrains.toolbox.api.remoteDev.connection.ToolboxProxySettings
 import com.jetbrains.toolbox.api.remoteDev.states.EnvironmentStateColorPalette
 import com.jetbrains.toolbox.api.remoteDev.ui.EnvironmentUiPageManager
 import com.jetbrains.toolbox.api.ui.ToolboxUi
+import com.jetbrains.toolbox.api.ui.components.UiComponents
 import kotlinx.coroutines.CoroutineScope
 
 /**
@@ -33,6 +34,7 @@ class CoderToolboxExtension : RemoteDevExtension {
         return CoderRemoteProvider(
             CoderToolboxContext(
                 ui,
+                serviceLocator.getService<UiComponents>(),
                 serviceLocator.getService<EnvironmentUiPageManager>(),
                 serviceLocator.getService<EnvironmentStateColorPalette>(),
                 serviceLocator.getService<RemoteToolsHelper>(),

src/main/kotlin/com/coder/toolbox/sdk/CoderRestClient.kt

@@ -161,11 +161,13 @@ open class CoderRestClient(
     }
 
     /**
-     * Retrieves the available workspaces created by the user.
+     * Retrieves workspaces matching the provided Coder search query.
      * @throws [APIResponseException].
      */
-    suspend fun workspaces(): List<Workspace> {
-        val workspacesResponse = callWithRetry { retroRestClient.workspaces("owner:me") }
+    suspend fun workspaces(searchQuery: String? = null): List<Workspace> {
+        val workspacesResponse = callWithRetry {
+            retroRestClient.workspaces(searchQuery)
+        }
         if (!workspacesResponse.isSuccessful) {
             throw APIResponseException(
                 "retrieve workspaces",
@@ -241,6 +243,26 @@ open class CoderRestClient(
         }
     }
 
+    /**
+     * Retrieves all templates the authenticated user can access.
+     * @throws [APIResponseException].
+     */
+    suspend fun templates(): List<Template> {
+        val templatesResponse = callWithRetry { retroRestClient.templates() }
+        if (!templatesResponse.isSuccessful) {
+            throw APIResponseException(
+                "retrieve templates",
+                url,
+                templatesResponse.code(),
+                templatesResponse.parseErrorBody(moshi)
+            )
+        }
+
+        return requireNotNull(templatesResponse.body()) {
+            "Successful response returned null body or templates"
+        }
+    }
+
     /**
      * @throws [APIResponseException].
      */
@@ -448,4 +470,4 @@ private fun Response<*>.parseErrorBody(moshi: Moshi): ApiErrorResponse? {
     } catch (e: Exception) {
         null
     }
-}
+}

src/main/kotlin/com/coder/toolbox/sdk/ex/APIResponseException.kt

@@ -12,6 +12,17 @@ class APIResponseException(action: String, url: URL, code: Int, errorResponse: A
     val isUnauthorized = HttpURLConnection.HTTP_UNAUTHORIZED == code
     val isTokenExpired = isUnauthorized && reason?.contains("API key expired") == true
 
+    /** True when the server rejected the request because of bad input (e.g. an invalid search query). */
+    val isValidationError = HttpURLConnection.HTTP_BAD_REQUEST == code && !errorResponse?.validations.isNullOrEmpty()
+
+    /**
+     * A short, user-facing description of a validation failure, combining the server message with the
+     * individual field details. Null when the response carried no validation errors.
+     */
+    val validationMessage: String? = errorResponse?.validations
+        ?.takeIf { it.isNotEmpty() }
+        ?.joinToString(separator = " ", prefix = "${errorResponse.message} ") { it.detail }
+
     companion object {
         private fun formatToPretty(
             action: String,

src/main/kotlin/com/coder/toolbox/sdk/v2/CoderV2RestFacade.kt

@@ -35,7 +35,7 @@ interface CoderV2RestFacade {
      */
     @GET("api/v2/workspaces")
     suspend fun workspaces(
-        @Query("q") searchParams: String,
+        @Query("q") searchParams: String?,
     ): Response<WorkspacesResponse>
 
     /**
@@ -58,6 +58,12 @@ interface CoderV2RestFacade {
         @Body createWorkspaceBuildRequest: CreateWorkspaceBuildRequest,
     ): Response<WorkspaceBuild>
 
+    /**
+     * Retrieves all templates the authenticated user can access.
+     */
+    @GET("api/v2/templates")
+    suspend fun templates(): Response<List<Template>>
+
     @GET("api/v2/templates/{templateID}")
     suspend fun template(
         @Path("templateID") templateID: UUID,

src/main/kotlin/com/coder/toolbox/sdk/v2/models/ApiErrorResponse.kt

@@ -7,4 +7,11 @@ import com.squareup.moshi.JsonClass
 data class ApiErrorResponse(
     @Json(name = "message") val message: String,
     @Json(name = "detail") val detail: String?,
+    @Json(name = "validations") val validations: List<FieldValidation>? = null,
+)
+
+@JsonClass(generateAdapter = true)
+data class FieldValidation(
+    @Json(name = "field") val field: String,
+    @Json(name = "detail") val detail: String,
 )