impl: start the workspace via Coder CLI (#221)

Netflix uses custom MFA that requires CLI middleware to handle auth
flow. The custom CLI implementation on their side intercepts 403
responses from the REST API, handles the MFA challenge, and retries the
rest call again. The MFA challenge is handled only by the `start` and
`ssh` actions. The remaining actions can go directly to the REST
endpoints because of the custom header command that provides MFA tokens
to the http calls.

Both Gateway and VS Code extension delegate the start logic to the CLI,
but not Toolbox which caused issues for the customer. This PR ports some
of the work from Gateway in Coder Toolbox.

Author: fioan89

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - application name can now be displayed as the main title page instead of the URL
 
+### Changed
+
+- workspaces are now started with the help of the CLI
+
 ## 0.7.2 - 2025-11-03
 
 ### Changed

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

@@ -26,6 +26,7 @@ import com.jetbrains.toolbox.api.ui.actions.ActionDescription
 import com.jetbrains.toolbox.api.ui.components.TextType
 import com.squareup.moshi.Moshi
 import kotlinx.coroutines.CoroutineName
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -36,6 +37,7 @@ import kotlinx.coroutines.launch
 import kotlinx.coroutines.withTimeout
 import java.io.File
 import java.nio.file.Path
+import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.time.Duration.Companion.minutes
 import kotlin.time.Duration.Companion.seconds
 
@@ -69,6 +71,7 @@ class CoderRemoteEnvironment(
     private val networkMetricsMarshaller = Moshi.Builder().build().adapter(NetworkMetrics::class.java)
     private val proxyCommandHandle = SshCommandProcessHandle(context)
     private var pollJob: Job? = null
+    private val startIsInProgress = AtomicBoolean(false)
 
     init {
         if (context.settingsStore.shouldAutoConnect(id)) {
@@ -120,9 +123,29 @@ class CoderRemoteEnvironment(
                 )
             } else {
                 actions.add(Action(context, "Start") {
-                    val build = client.startWorkspace(workspace)
-                    update(workspace.copy(latestBuild = build), agent)
-
+                    try {
+                        // needed in order to make sure Queuing is not overridden by the
+                        // general polling loop with the `Stopped` state
+                        startIsInProgress.set(true)
+                        val startJob = context.cs
+                            .launch(CoroutineName("Start Workspace Action CLI Runner") + Dispatchers.IO) {
+                                cli.startWorkspace(workspace.ownerName, workspace.name)
+                            }
+                        // cli takes 15 seconds to move the workspace in queueing/starting state
+                        // while the user won't see anything happening in TBX after start is clicked
+                        // During those 15 seconds we work around by forcing a `Queuing` state
+                        while (startJob.isActive && client.workspace(workspace.id).latestBuild.status.isNotStarted()) {
+                            state.update {
+                                WorkspaceAndAgentStatus.QUEUED.toRemoteEnvironmentState(context)
+                            }
+                            delay(1.seconds)
+                        }
+                        startIsInProgress.set(false)
+                        // retrieve the status again and update the status
+                        update(client.workspace(workspace.id), agent)
+                    } finally {
+                        startIsInProgress.set(false)
+                    }
                 }
                 )
             }
@@ -241,6 +264,10 @@ class CoderRemoteEnvironment(
      * Update the workspace/agent status to the listeners, if it has changed.
      */
     fun update(workspace: Workspace, agent: WorkspaceAgent) {
+        if (startIsInProgress.get()) {
+            context.logger.info("Skipping update for $id - workspace start is in progress")
+            return
+        }
         this.workspace = workspace
         this.agent = agent
         wsRawStatus = WorkspaceAndAgentStatus.from(workspace, agent)

src/main/kotlin/com/coder/toolbox/cli/CoderCLIManager.kt

@@ -125,6 +125,7 @@ data class Features(
     val disableAutostart: Boolean = false,
     val reportWorkspaceUsage: Boolean = false,
     val wildcardSsh: Boolean = false,
+    val buildReason: Boolean = false,
 )
 
 /**
@@ -304,6 +305,25 @@ class CoderCLIManager(
         )
     }
 
+    /**
+     * Start a workspace. Throws if the command execution fails.
+     */
+    fun startWorkspace(workspaceOwner: String, workspaceName: String, feats: Features = features): String {
+        val args = mutableListOf(
+            "--global-config",
+            coderConfigPath.toString(),
+            "start",
+            "--yes",
+            "$workspaceOwner/$workspaceName"
+        )
+
+        if (feats.buildReason) {
+            args.addAll(listOf("--reason", "jetbrains_connection"))
+        }
+
+        return exec(*args.toTypedArray())
+    }
+
     /**
      * Configure SSH to use this binary.
      *
@@ -569,7 +589,8 @@ class CoderCLIManager(
                 Features(
                     disableAutostart = version >= SemVer(2, 5, 0),
                     reportWorkspaceUsage = version >= SemVer(2, 13, 0),
-                    version >= SemVer(2, 19, 0),
+                    wildcardSsh = version >= SemVer(2, 19, 0),
+                    buildReason = version >= SemVer(2, 25, 0),
                 )
             }
         }

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

@@ -241,6 +241,7 @@ open class CoderRestClient(
     /**
      * @throws [APIResponseException].
      */
+    @Deprecated(message = "This operation needs to be delegated to the CLI")
     suspend fun startWorkspace(workspace: Workspace): WorkspaceBuild {
         val buildRequest = CreateWorkspaceBuildRequest(
             null,

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

@@ -10,20 +10,41 @@ import java.util.UUID
  */
 @JsonClass(generateAdapter = true)
 data class WorkspaceBuild(
-    @Json(name = "template_version_id") val templateVersionID: UUID,
-    @Json(name = "resources") val resources: List<WorkspaceResource>,
-    @Json(name = "status") val status: WorkspaceStatus,
+    @property:Json(name = "template_version_id") val templateVersionID: UUID,
+    @property:Json(name = "resources") val resources: List<WorkspaceResource>,
+    @property:Json(name = "status") val status: WorkspaceStatus,
 )
 
 enum class WorkspaceStatus {
-    @Json(name = "pending") PENDING,
-    @Json(name = "starting") STARTING,
-    @Json(name = "running") RUNNING,
-    @Json(name = "stopping") STOPPING,
-    @Json(name = "stopped") STOPPED,
-    @Json(name = "failed") FAILED,
-    @Json(name = "canceling") CANCELING,
-    @Json(name = "canceled") CANCELED,
-    @Json(name = "deleting") DELETING,
-    @Json(name = "deleted") DELETED,
-}
+    @Json(name = "pending")
+    PENDING,
+
+    @Json(name = "starting")
+    STARTING,
+
+    @Json(name = "running")
+    RUNNING,
+
+    @Json(name = "stopping")
+    STOPPING,
+
+    @Json(name = "stopped")
+    STOPPED,
+
+    @Json(name = "failed")
+    FAILED,
+
+    @Json(name = "canceling")
+    CANCELING,
+
+    @Json(name = "canceled")
+    CANCELED,
+
+    @Json(name = "deleting")
+    DELETING,
+
+    @Json(name = "deleted")
+    DELETED;
+
+    fun isNotStarted(): Boolean = this != STARTING && this != RUNNING
+}

src/main/kotlin/com/coder/toolbox/util/CoderProtocolHandler.kt

@@ -84,7 +84,7 @@ open class CoderProtocolHandler(
             }
             reInitialize(restClient, cli)
             context.envPageManager.showPluginEnvironmentsPage()
-            if (!prepareWorkspace(workspace, restClient, workspaceName, deploymentURL)) return
+            if (!prepareWorkspace(workspace, restClient, cli, workspaceName, deploymentURL)) return
             // we resolve the agent after the workspace is started otherwise we can get misleading
             // errors like: no agent available while workspace is starting or stopping
             // we also need to retrieve the workspace again to have the latest resources (ex: agent)
@@ -180,6 +180,7 @@ open class CoderProtocolHandler(
     private suspend fun prepareWorkspace(
         workspace: Workspace,
         restClient: CoderRestClient,
+        cli: CoderCLIManager,
         workspaceName: String,
         deploymentURL: String
     ): Boolean {
@@ -207,7 +208,7 @@ open class CoderProtocolHandler(
                     if (workspace.outdated) {
                         restClient.updateWorkspace(workspace)
                     } else {
-                        restClient.startWorkspace(workspace)
+                        cli.startWorkspace(workspace.ownerName, workspace.name)
                     }
                 } catch (e: Exception) {
                     context.logAndShowError(

src/test/kotlin/com/coder/toolbox/cli/CoderCLIManagerTest.kt

@@ -976,8 +976,24 @@ internal class CoderCLIManagerTest {
         val tests =
             listOf(
                 Pair("2.5.0", Features(true)),
-                Pair("2.13.0", Features(true, true)),
-                Pair("4.9.0", Features(true, true, true)),
+                Pair("2.13.0", Features(disableAutostart = true, reportWorkspaceUsage = true)),
+                Pair(
+                    "2.25.0",
+                    Features(
+                        disableAutostart = true,
+                        reportWorkspaceUsage = true,
+                        wildcardSsh = true,
+                        buildReason = true
+                    )
+                ),
+                Pair(
+                    "4.9.0", Features(
+                        disableAutostart = true,
+                        reportWorkspaceUsage = true,
+                        wildcardSsh = true,
+                        buildReason = true
+                    )
+                ),
                 Pair("2.4.9", Features(false)),
                 Pair("1.0.1", Features(false)),
             )