Workspace IDE Access

Crafting workspaces can be accessed from IDEs that support remote development via SSH. After running cs login, ~/.ssh/config is updated with the configuration required to reach Crafting workspaces. Any IDE that honors ~/.ssh/config can connect to a workspace by using the following hostname:

<WORKSPACE-NAME>--<SANDBOX-NAME>-<ORG-NAME>.<SERVER_DNS>

The user is always owner, which is already configured in ~/.ssh/config.

The Crafting CLI provides sub-commands for launching popular IDEs directly:

All of the above commands support the following flag:

JetBrains IDE

JetBrains offers a suite of powerful, feature-rich IDEs for the most common programming languages. For remote development, JetBrains provides JetBrains Gateway on the client side, which works together with an IDE backend running on the server.

The cs jetbrains command takes care of:

…all in a single command.

Use the --ide flag to launch a specific IDE rather than the default IntelliJ. For example:

On first use, JetBrains Gateway downloads the server-side package into the workspace and the client software locally, so the initial launch may take a while.

In the definition of a Template or Sandbox, additional properties can be provided to specify the default IDE, version, and installation folder inside the workspace. For example, add the following customization section to the definition:

workspaces:
- name: example
...
customizations:
- property_set:
    type: crafting.dev/sandbox/jetbrains
    properties:
      workspace: example
      ide_code: IU
      ide_version: 2025.1.1
      ide_folder: ideaIU-2025.1.1

Where:

Prelaunch Remote Server

To reduce the start time of cs jetbrains, the remote server matching the specified version can be preinstalled in the base snapshot and prelaunched during workspace startup. The remote dev server can be launched from inside a Crafting workspace using:

cs jetbrains remote-dev-server run ${PROJECT_DIR}

Typically this is wired up as a daemon of a checkout. For example:

workspaces:
- name: example
  checkouts:
  - path: src
    repo:
      ...
    manifest:
      overlays:
      - inline: |
          ...
          daemons:
              remote-dev-server:
                 run:
                    cmd: cs jetbrains remote-dev-server run

Note: stopping the daemon may not stop the remote-dev-server in the background if there is an active client session connected. To forcibly stop the remote-dev-server when stopping the daemon, add the --terminate-dev-server flag to the command line.

Warm-up Index

The first launch of the remote server on a code repository takes longer because the source code must be indexed. This indexing step can be performed explicitly during workspace startup to save time when a client connects later. Run the following command to warm up the index explicitly:

cs jetbrains remote-dev-server warmup ${PROJECT_DIR}

This is commonly added to a post-checkout hook, or run before the remote server starts as a daemon.

Troubleshooting

Unable to launch IDE client (macOS only)

When this happens, the UI may show progress of downloading the IDE thin client (or it may not, if the client is already downloaded), but no IDE UI is launched afterward. From the terminal, you may see a log message such as:

WARN - #c.i.r.d.CodeWithMeClientDownloader - Running client process failed after specified number of attempts

If info-level logging is enabled, you may also see something like error=Error Domain=NSOSStatusErrorDomain Code=-10661.

This is caused by the cs CLI and/or the JetBrains Gateway being downloaded for a different CPU architecture, after which the gateway downloads an IDE thin client for the wrong architecture.

A clean fix is:

Then run cs jetbrains again to verify the issue is resolved.

See Also