A remote workspace is a fully-configured, on-demand development environment that lives in the cloud. Remote workspaces give you the same tools and dependencies you’d expect locally—without any machine-setup friction—so you can build, test, and run code directly from Factory.

​
System Requirements

  • A repository enabled in Factory
  • A valid devcontainer.json (see below)
  • Manager role or higher to create remote workspaces
1

Open Session Settings

  1. In Factory, click the Settings icon from the left sidebar.
  2. Select Session.
  3. Scroll down to Remote Workspaces.
2

Create a New Remote Workspace

  1. Click Create Workspace.
  2. Enter the repository you want to use.
  3. Give your workspace a friendly name (e.g., “frontend-workspace”).
  4. (Optional) Upload a custom devcontainer.json.
  5. Click Create.
Factory clones your repo and prepares the environment—this can take a minute for large projects.
3

Verify Workspace Ready

The new workspace appears in the list with a status indicator. Once it shows Ready, you can use it from any session.

​
Understanding Devcontainers

A devcontainer defines everything your remote workspace needs—language runtimes, tools, and commands—so every workspace is identical and reproducible.

​
Minimal JavaScript Example

{
  "name": "Node.js",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20-bullseye",
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "settings": {
    "terminal.integrated.scrollback": 10000
  }
}
Save this file as .devcontainer/devcontainer.json in your repo or upload it when creating the workspace.

​
Launching a Remote Workspace inside a Session

1

Open or Start a Session

Join any Factory session as usual.
2

Connect to Cloud Machine

  1. Click the CPU icon in the top-right toolbar.
  2. Choose Remote Machine.
  3. Select the workspace you created earlier.
  4. Factory attaches the remote workspace to your session.
3

Confirm Connection

A green indicator and machine name appear next to the CPU icon. You’re now interacting with the cloud workspace.

​
Everyday Usage

Run CLI Commands

Use the Terminal toolkit to execute commands like: 
npm run dev
pytest
git status
Output streams live into chat and logs.

Edit & Save Files

Open files from the repo, make changes, and save.
Files persist in the remote workspace and can be committed upstream when ready.

Port Forwarding

If your devcontainer exposes ports (e.g., 3000), Factory auto-detects and adds them to the Ports panel for browser preview.

Auto-Save Controls

Auto-save is disabled by default—enable it from the Session Settings panel whenever you want live file syncing.

​
Troubleshooting & Help

Need More Help?

Visit the full Remote Workspace Troubleshooting Guide