Create a Workspace

A workspace is a containerized development environment that holds a project's source and the tools needed to work on it. A provider creates the environment it runs in.

Devsy uses the devcontainer.json specification, which VS Code dev containers and GitHub Codespaces also use, so a project that already has one needs no extra setup. If there is none, Devsy detects the project's language and offers a template.

A workspace keeps its state when you stop and restart it. Once it exists, it is reachable over SSH at WORKSPACE_NAME.devsy, and Devsy can open it in a local IDE.

Create a workspaceCopy Anchor Link

The source can be a Git repository, a local folder, or an image such as golang:latest.

Devsy DesktopCopy Anchor Link

Open Workspaces and click Create. The wizard has five steps:

1. Provider. Pick an initialized provider. You cannot change it later.
2. Source. Pick a template or an image, or enter a Git URL, image, or local path. Show advanced options lets you set the branch, commit, or PR, a project subfolder, the folder to open, the devcontainer.json path, and a prebuild repository.
3. IDE. Optional. The default is none.
4. Review. Check the workspace name and configuration. If the image has no build for your architecture, you can turn on Run under emulation.
5. Launch. Devsy creates the workspace and streams progress, then opens your IDE.

The desktop app runs devsy workspace up for you.

Devsy CLICopy Anchor Link

Install the CLI and add a provider, for example Docker:

devsy provider add docker

Git repository

devsy workspace up github.com/microsoft/vscode-remote-try-node

Add @ and a ref to pick a branch, commit, or pull request:

devsy workspace up github.com/microsoft/vscode-remote-try-node@main
devsy workspace up github.com/microsoft/vscode-remote-try-node@sha256:15ba80171af11374143288fd3d54898860107323
devsy workspace up github.com/microsoft/vscode-remote-try-node@pull/108/head # GitHub only

Devsy forwards your git credentials, so private repositories work. Use --id to name the workspace, which lets you create several from one repository.

Local folder

devsy workspace up ./path/to/my-folder

Devsy copies the folder to the provider and builds from its devcontainer.json. See .devsyignore to leave files out.

Image

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

Devsy generates a devcontainer.json that names the image. To run an image built for another architecture, add --platform linux/amd64. Emulation can be much slower, so prefer multi-arch images.

The desktop app also has a catalog of ready-made images and flags any that do not fit your machine.

Existing container

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

Only the docker provider supports this, and --recreate is rejected for these workspaces.

.devsyignoreCopy Anchor Link

Put a .devsyignore file in the root of a local workspace folder to leave files out of the upload when the provider streams the folder, as Kubernetes does. It uses Docker ignore syntax. Paths are relative to the folder, and the last matching rule wins.

big/
**/node_modules/
docs/*.tgz
build/
!build/keep.txt

• A missing or empty file uploads everything.
• An unreadable file or an invalid pattern stops the upload with an error that names the file.
• It does not apply to extra bind mounts, to local Docker bind mounts, to remote Git clones, or to image builds, which use their own rules. .gitignore and .dockerignore are not used in its place.

Inspect a workspaceCopy Anchor Link

devsy workspace describe my-workspace

This prints the configuration and live state. Add --result-format json for scripts. Other commands:

• devsy workspace status <name> shows whether it is running or stopped.
• devsy workspace logs <name> streams the agent logs.
• devsy workspace ping <name> checks that the agent is reachable.
• devsy workspace troubleshoot <name> bundles diagnostics for an issue report.

Recreate a workspaceCopy Anchor Link

Recreating applies changes to devcontainer.json or its Dockerfile. If a prebuild repository is configured, Devsy looks there for the new image first.

devsy workspace up my-workspace --recreate

Reset a workspaceCopy Anchor Link

A reset starts from a clean slate. It pulls the latest Git changes or uploads your local folder again, and it keeps nothing.

devsy workspace up my-workspace --reset