Create a Workspace

Create workspaces from the Devsy CLI or the Desktop app. A workspace's source can be a Git repository, a local path, or a Docker image (e.g. golang:latest).

Once created, the workspace is reachable through the SSH host WORKSPACE_NAME.devsy, or Devsy can open it in a local IDE like VS Code or IntelliJ.

info

A workspace is defined by a devcontainer.json. If none exists, Devsy detects the project's language and picks a matching template.

Via Devsy Desktop Application

Open the Workspaces view and click Create to launch the wizard. It walks through five steps:

Provider — pick an initialized provider. Cannot be changed later. If none exists, the wizard offers to add one.
Source — choose a Quick Start template, browse the image catalog, or enter a custom Git URL / image / local path. Show advanced options reveals:
- Ref Type and value (branch, commit, or PR number) for Git sources.
- Project subfolder within the repo.
- Open folder in container (where the editor opens).
- Dev container config path (override .devcontainer/devcontainer.json location).
- Prebuild repository for cached images.
IDE — pick one or more IDEs to open the workspace with. Optional; defaults to none.
Review — adjust the auto-derived workspace name and confirm the configuration. If the chosen image has no build for your machine architecture, the Review step shows a compatibility warning and a Run under emulation toggle.
Launch — Devsy creates the workspace and streams progress. A 10-minute watchdog cancels the launch if it stalls. The chosen IDE opens on success.

info

Under the hood, the Desktop Application will call the CLI command devsy workspace up REPOSITORY

Note

You can set the location of your devsy home by passing the --home={home_path} flag, or by setting the env var DEVSY_HOME to your desired home directory.

This can be useful if you are having trouble with a workspace trying to mount to a windows location when it should be mounting to a path inside the WSL VM.

For example: setting --home=/mnt/c/Users/MyUser/ will result in a workspace path of something like /mnt/c/Users/MyUser/.devsy/contexts/default/workspaces/...

Via Devsy CLI

Install the Devsy CLI and add a provider to host the workspace (such as local docker):

# Add a provider if you haven't already
devsy provider add docker

Git Repository

Start a new workspace from a Git repository:

# Create from Git repository
devsy workspace up github.com/microsoft/vscode-remote-try-node

Append a commit hash, branch, or pull request slug to the URL to check out a specific ref:

Branch: devsy workspace up github.com/microsoft/vscode-remote-try-node@main
Commit: devsy workspace up github.com/microsoft/vscode-remote-try-node@sha256:15ba80171af11374143288fd3d54898860107323
PR:     devsy workspace up github.com/microsoft/vscode-remote-try-node@pull/108/head # Only works for GitHub!

Private Git Repositories

Devsy forwards your git credentials to the remote machine so private repositories work too.

Multiple workspaces from the same repository

Pass --id to override the workspace name. This lets you spin up multiple workspaces from one repository.

Local Path

Create a workspace from a local folder:

# Create from a local path
devsy workspace up ./path/to/my-folder

Devsy syncs the folder onto the remote machine and builds the dev environment from the devcontainer.json.

Docker Image

Create a workspace from a Docker image:

# Create from a docker image
devsy workspace up ghcr.io/my-org/my-repo:latest

Devsy generates the following .devcontainer.json:

{
    "image": "ghcr.io/my-org/my-repo:latest"
}

Run under a different platform

Pass --platform to run the container under a non-native architecture (via QEMU emulation on Docker). This is useful for images that only ship linux/amd64 when you're on Apple Silicon.

devsy workspace up ghcr.io/my-org/my-repo:latest --platform linux/amd64

Emulation cost

Emulated containers can be significantly slower than native ones. Prefer multi-arch images when available.

Image catalog (Desktop)

Devsy Desktop ships a curated catalog of pre-built devcontainer images. The Source step of the workspace wizard surfaces them in an image picker and flags incompatible images (e.g. an arm64-only image on an amd64 host). The CLI accepts any of these images as a --source or positional argument.

Existing local container

Bind a workspace to a container that is already running:

devsy workspace up my-workspace --source container:$CONTAINER_ID

Only the docker provider supports this.

info

--recreate is rejected on a workspace backed by an existing container.

Inspect a workspace

devsy workspace describe <name> prints a workspace's full configuration plus its live state. By default it renders a Field | Value table; pass --result-format json for machine-readable output (Devsy Desktop uses the JSON form).

devsy workspace describe my-workspace
devsy workspace describe my-workspace --result-format json

Other useful inspection commands:

devsy workspace status <name> — quick state check (Running, Stopped, NotFound).
devsy workspace logs <name> — stream the agent logs from the container.
devsy workspace ping <name> — verify the agent is reachable through the tunnel.
devsy workspace troubleshoot <name> — bundle diagnostics for issue reports.

Recreating a workspace

Recreating a workspace re-applies changes from the devcontainer.json or its Dockerfile. Use this after editing the devcontainer or pulling new changes that affect the dev environment. If a prebuild repository is configured, Devsy looks for the updated image there first and falls back to building locally.

Only changes inside the project path or mounted volumes survive a recreate. Everything else in the container is lost.

Via Devsy CLI

Rebuild an existing workspace:

devsy workspace up my-workspace --recreate

Resetting a workspace

Reset rebuilds the workspace from a clean slate — it pulls the latest Git changes or re-uploads your local folder. Use it instead of --recreate when you need a full restart.

A reset preserves nothing.

Via Devsy CLI

Reset an existing workspace:

devsy workspace up my-workspace --reset