Create a Workspace
A workspace is a containerized development environment with a project's source and its tools. A provider creates the environment.
Devsy uses the devcontainer.json format, which VS Code dev containers and GitHub Codespaces also use. A project with a devcontainer.json needs no extra setup. Without one, Devsy detects the project's language and offers a template.
A workspace keeps its state when you stop and restart it. While it runs, it accepts SSH connections at WORKSPACE_NAME.devsy. Devsy opens it in a local IDE if you select one.
Create a workspace
The source can be a Git repository, a local folder, or an image such as golang:latest.
Devsy Desktop
Open Workspaces and click Create. The wizard has five steps:
- Provider. Pick an initialized provider. You cannot change it later.
- 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.jsonpath, and a prebuild repository. - IDE. Optional. The default is none.
- Review. Check the workspace name and configuration. If the image has no build for your architecture, you can turn on Run under emulation.
- Launch. Devsy creates the workspace and streams progress, then opens your IDE if you selected one.
The desktop app runs devsy workspace up for you. Desktop launches run without a terminal, so if a postStartCommand needs input, create or start the workspace in an attached CLI terminal and open it from Desktop afterward.
Workspace IDs
The workspace name is its ID. Use lowercase ASCII letters (a-z), digits (0-9), and hyphens (-), with a maximum of 48 characters.
Desktop suggests a valid ID from your source. A local folder named Backend gets the suggestion backend. The source path keeps its original case. If you enter a name yourself, it must follow the same rules:
devsy workspace up ./Projects/Backend --id backendWorkspace IDs
Uppercase workspace IDs are rejected before creation starts. Startup failures appear as failed tasks in Desktop.
Devsy CLI
Install the CLI, then add a provider. This example uses Docker:
devsy provider add dockerGit repository
devsy workspace up github.com/microsoft/vscode-remote-try-nodeAdd @ 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 onlyDevsy forwards your Git credentials, so private repositories work. Use --id to name the workspace and create several from one repository.
Local folder
devsy workspace up ./path/to/my-folderDevsy copies the folder to the provider and builds from its devcontainer.json. See .devsyignore to exclude files.
Image
devsy workspace up ghcr.io/my-org/my-repo:latestDevsy generates a devcontainer.json that names the image. To run an image built for another architecture, add --platform linux/amd64. Emulation is slower, so prefer multi-arch images.
Desktop also lists ready-made images and marks the ones that do not fit your machine.
Existing container
devsy workspace up my-workspace --source container:$CONTAINER_IDOnly the docker provider supports this, and --recreate is rejected for these workspaces.
Devsy home
Pass --home=PATH or set DEVSY_HOME to change where Devsy keeps its data. Use this on WSL if a workspace tries to mount a Windows path instead of a path inside WSL.
Read setup output
Devsy keeps the output of the build and each lifecycle hook, such as postCreateCommand, after devsy workspace up finishes. To read it:
devsy workspace logs WORKSPACE_NAME --source setup --list
devsy workspace logs WORKSPACE_NAME --source setup --run RUN_ID --result-format=plainThe run ID appears in the result of devsy workspace up and in the output of a detached creation task. Use --list to find IDs for earlier runs.
For a detached creation, Devsy waits up to 30 seconds for the background worker to register. Workspace setup continues after the command returns. If the worker cannot register within that time, the launch fails and Devsy cleans it up.
- Hooks that run after
waitFor(defaultupdateContentCommand) can finish afterupreturns. Their output joins the same run. Add--followto watch them. - A hook that an earlier attempt already marked is skipped with the reason
already_attempted. This does not mean the earlier attempt succeeded. Check that run. postAttachCommandruns on every attach. Each run is recorded separately.
See Troubleshooting for all options and Setup history for limits and redaction.
Answer prompts in postStartCommand
Some postStartCommand hooks ask for input, such as a name or a token. Add --interactive-post-start to connect your terminal to that hook:
devsy workspace up ./project --interactive-post-start --ide noneThis devcontainer.json asks for a name when the workspace starts:
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"postStartCommand": "read -r -p 'Name: ' NAME && echo \"Hello, $NAME\""
}read -p works only in Bash. If the hook runs under sh, use printf 'Name: ' and then read -r NAME.
The prompt appears as soon as the hook asks for it. Type your answer in the terminal. For that run, devsy workspace up waits for postStartCommand to finish before it returns, even if your project sets an earlier waitFor. Hooks before postStartCommand still run in their usual order. Devsy does not change waitFor in your project, and a later waitFor value still applies. The option gives input only to postStartCommand. postAttachCommand and the other hooks still run without input.
postStartCommand can be a string, an array of arguments, or an object with one named command. An object with two or more named commands fails before any post-start command runs. The error gives the object's position, for example postStartCommand merged index 0 has multiple nonempty named commands. Without the option, the named commands in one object still run in parallel.
Running devsy workspace up on a workspace that has already started does not run postStartCommand again, with or without the option. No prompt appears and the start finishes normally. The skip reason is recorded in Setup history. Stopping and starting the workspace runs postStartCommand again. Start it with the option to answer the prompt:
devsy workspace up my-workspace --interactive-post-startThe option needs an attached terminal for stdin and stdout, and plain output. Devsy rejects it before it starts the workspace when you combine it with --detach, --prebuild, --recovery, --skip-post-start, or --skip-non-blocking-commands. It also rejects it for JSON output, for a script or pipe without a terminal, and for Devsy Desktop launches. Troubleshooting lists each error message.
.devsyignore
Put a .devsyignore file in the root of a local workspace folder to leave files out of the upload when Devsy uploads the folder to the provider, as it does for Kubernetes. The file uses Docker ignore syntax. Paths are relative to the folder. 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 invalid pattern stops the upload with an error naming the file.
- The file filters only the workspace folder upload. Extra bind mounts, local Docker bind mounts, and image builds follow their own rules. After a Git clone, Devsy deletes the paths the file lists, matched literally. A negated rule such as
!build/keep.txtcannot restore a file deleted withbuild/after a Git clone. Devsy does not read.gitignoreor.dockerignore.
Inspect a workspace
devsy workspace describe my-workspaceThis prints the configuration and live state. Add --result-format json for scripts. Related 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 workspace
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 --recreateRecreating keeps only the project folder and mounted volumes. Anything else in the container is lost.
Reset a workspace
A reset pulls the latest Git changes, or uploads your local folder again. For local-folder workspaces, Devsy removes and re-seeds its managed named volumes. Bind mounts and unmanaged volumes stay.
devsy workspace up my-workspace --reset