Skip to main content

Connect a Workspace and Machine

Everything Helix does starts from a workspace. Reading files, running commands, and editing code all depend on Helix knowing which machine and which project directory it should work in.

This tutorial covers the essential first step: connect Helix to a local folder, remote server, or VM workspace, and make sure the connection is actually usable.

See the Full Flow First​

Workspace launchpad and add-workspace modal overview

The workspace launchpad is on the left; the add-workspace entry and connection panel are on the right. Let's walk through the flow in order.

Step 1: Open the Add Workspace Entry​

Click Add Workspace in the quick actions on the left.

Add Workspace entry in the left quick actions area

This opens the workspace launchpad and shows the modal for creating or connecting a workspace.

Step 2: Choose a Workspace Type​

In the modal, choose the workspace type first. The common options are:

  • Local workspace: the project is on this computer
  • Remote workspace: the project is on an SSH server
  • VM workspace: the project runs inside a Helix-managed virtual machine
Server address and project path area in the add-workspace modal

For a remote workspace, enter the server address and finish connecting before choosing the project directory.

Step 3: Confirm the Machine Is Connected​

Once the connection succeeds, the server card switches to the connected state and the project directory appears in the same modal.

Workspace connection success state with directory selection

Don't just check that the modal is open. Confirm two things:

  1. The machine state shows connected
  2. The target project directory is visible or selectable

Step 4: Verify the Workspace in the List​

Back in the workspace list, you should see the current workspace, connection mode, and recently used projects.

Workspace list and connection mode view

If the workspace appears here and can be opened again, the setup is ready.

What You Should Have Now​

After this tutorial, you should have a usable Helix workspace:

  • Helix knows which project directory to operate on
  • The AI can read files in that directory
  • The terminal opens in the workspace automatically
  • Model setup, conversations, and Manager tasks now have a real project target

Next Step​

Continue with Get to Know the Helix Interface and learn where the main controls live.