Skip to content
Ordin Labs

Accessing workspaces with SSH

SSH Help

Section titled “SSH Help”

All workspaces in Workspace Manager are accessible via SSH, allowing you to use your favorite IDE and tools.

Configuration

Section titled “Configuration”

Workspaces are accessible via SSH using key-based authentication. You configure SSH public keys on your profile. All SSH keys on your profile can be used to access any workspace you have access to. Instructions for connecting over SSH are available on each workspace’s status page.

The SSH command is in the format

Terminal window
ssh <workspace_id>@<ssh_endpoint>

You can also manually configure SSH client configuration for your workspaces:

Host wsm.*
  HostName <ssh_endpoint>
  ForwardAgent yes
  IdentitiesOnly yes


Host wsm.my_workspace
  User <workspace_id>


Host wsm.my_other_workspace
  User <workspace_id>

You can get a workspace’s ID from the URL when viewing the workspace status page, which is in this format:

/project/<project_id>/workspaces/<workspace_id>/status

Automatic Configuration Update

Section titled “Automatic Configuration Update”

This configuration can be automatically downloaded, placed under ~/.ssh/config.d, and included in your primary ~/.ssh/config file using the following WSM CLI command:

Terminal window
wsm-cli ssh config-update

This command will:

  1. Download your personalized SSH configuration
  2. Save it to ~/.ssh/config.d/wsm-config
  3. Update your ~/.ssh/config to include the WSM configuration

See the CLI documentation for more information on the CLI.

SSH Keys

Section titled “SSH Keys”

The SSH keys for all developers on a given project are automatically installed in all workspaces belonging to that project.

Setting Your SSH Key

Section titled “Setting Your SSH Key”
  1. Navigate to your profile page in the WSM admin
  2. Go to the “Details” section
  3. Add or update your SSH public key
  4. Save changes

Your key will be automatically deployed to all workspaces in projects you have access to.

Getting Added to a Project

Section titled “Getting Added to a Project”

To be added to a project, contact one of that project’s administrators. Once added, your SSH key will be automatically installed in all workspaces for that project.

SSH Autocomplete

Section titled “SSH Autocomplete”

The WSM CLI provides an SSH autocomplete implementation that is platform-agnostic and include-aware.

Setup Autocomplete

Section titled “Setup Autocomplete”

To initialize autocomplete, run the following command and follow the OS/Shell-specific instructions:

Terminal window
wsm-cli ssh autocomplete setup

This will provide instructions for:

  • Bash: Add to ~/.bashrc or ~/.bash_profile
  • Zsh: Add to ~/.zshrc
  • Fish: Add to ~/.config/fish/config.fish

Connecting to Workspaces

Section titled “Connecting to Workspaces”

Once your SSH configuration is set up, connecting to a workspace is simple:

Terminal window
# Connect to a workspace
ssh workspace-name


# Or use the full hostname
ssh workspace-name.project-name.wsm.example.com

The SSH configuration handles the port mapping automatically.

Using with IDEs

Section titled “Using with IDEs”

VS Code

Section titled “VS Code”
  1. Install the “Remote - SSH” extension
  2. Open the Command Palette (Cmd/Ctrl+Shift+P)
  3. Select “Remote-SSH: Connect to Host”
  4. Choose your workspace from the list
  5. VS Code will connect and you can work remotely

PHPStorm / IntelliJ

Section titled “PHPStorm / IntelliJ”
  1. Go to Tools → Deployment → Configuration
  2. Click + to add a new SFTP server
  3. Enter your workspace hostname
  4. Set authentication to “Key pair”
  5. Map your local and remote paths
  6. Click OK and test the connection

Other IDEs

Section titled “Other IDEs”

Any IDE that supports SSH/SFTP can connect to workspaces. Use the hostname from your SSH config and your SSH key for authentication.

Troubleshooting

Section titled “Troubleshooting”

Connection Refused

Section titled “Connection Refused”

If you get a “Connection refused” error:

  1. Verify the workspace is running (check WSM admin dashboard)
  2. Ensure your SSH config is up to date: wsm-cli ssh config-update
  3. Check that your SSH key is properly configured in your profile

Permission Denied

Section titled “Permission Denied”

If you get a “Permission denied” error:

  1. Verify your SSH key is added to your WSM profile
  2. Check that you have access to the project
  3. Ensure your SSH key has the correct permissions: chmod 600 ~/.ssh/id_rsa

Host Key Verification Failed

Section titled “Host Key Verification Failed”

If you get a host key verification error:

  1. Remove the old host key: ssh-keygen -R workspace-name
  2. Try connecting again and accept the new host key

Security Best Practices

Section titled “Security Best Practices”
  • Use SSH keys only - Password authentication is disabled
  • Protect your private key - Never share your private SSH key
  • Use a passphrase - Protect your SSH key with a strong passphrase
  • Rotate keys regularly - Update your SSH keys periodically
  • One key per device - Use different SSH keys for different machines

Next Steps

Section titled “Next Steps”