Run Your Project in a Dev Container, in Zed

Starting from Zed v0.218, you can now work inside Dev Containers using Docker, enabling the creation of consistent, stable, and reproducible development environments.

What are Dev Containers?

The Development Containers Specification is an open standard for how to set up Dockerized development environments, which offers you a consistent experience for your code base right out of the box.

Think about some of your longest first-day-of-coding experiences. What made the setup process difficult? Often, getting off the ground is slowed down by inconsistent environments:

You need the correct version of a build tool on your path (e.g., Go or npm), or an associated runtime (e.g., .NET)
You might need certain local storage technologies available (Postgres, or Mysql)
You might need infrastructural tools, like Kubernetes
You'll likely need certain environment variables set up

In the past, organizations managed the knowledge of how to set up your machine either tribally or via documentation. Often, you'd simply need to pair with a longer-tenured engineer to get your environment set up, which is a pretty expensive use of engineering time. In more organized cases, there might be a README to run through, but the README would always run the risk of falling out of date with the up-to-date needs of the engineering team.

Dev Containers solves this problem with an infrastructure-as-code approach. Teams define the environment that they need for writing code in a JSON file at a well-known path: <ProjectRoot>/.devcontainer/devcontainer.json. The JSON file can derive from known templates and import published features, but it also provides a way to define the container entirely in a Dockerfile or docker-compose.yaml. Check out more details on how the spec works.

How to use it

If you're using Zed on a project that contains a /.devcontainer/devcontainer.json file, a toast will pop up at the bottom right of the UI asking whether you'd like to open it in a Dev Container:

The toast for opening your project in a Dev Container.

If you dismiss the toast, but still want to open the project in a Dev Container later, you can reach for the project: open remote action in the command palette or by clicking on the "File" menu and looking for "Open Remote…":

How to get access to the "Connect Dev Container" button.

After connecting, you can see you're running that project from a Dev Container through the title bar indication. And from here on out, all of Zed's features should just work. Zed will also automatically reconnect to the last Dev Container you used when you reopen the app after quitting.

The title bar indication you're running this project in a Dev Container.

How we built it

There were two aspects to enabling this feature:

Creating the Dev Container from a devcontainer.json specification, and
Connecting to a running Dev Container so that you can work within it

Let's go over our approaches to these two areas in reverse order.

Connecting to a running Dev Container

Zed has had the ability to work on a remote project via SSH for a while—learn more about it—and the underlying architecture ported to Dev Containers nicely.

Fundamentally, Zed enables remote development by running two instances: a Zed Remote Server on the destination, and a local version of Zed on your local host. The remote server handles what you might consider "backend" work: saving files, coordinating with Language Servers, parsing syntax trees, etc. Meanwhile, your local Zed continues to run the UI via GPUI, making the experience snappy.

These two servers communicate over standard IO: Zed local spawns Zed remote in the remote destination, and sends it information via the subprocess's Stdin. Zed remote then sends messages back to Zed local via its Stdout and Stderr streams, which Zed local reads. This strategy was originally developed for transport over an SSH connection, but it works well over docker exec, so it was just a matter of writing a new transport layer.

Creating the Dev Container from a devcontainer.json specification

Today, Zed takes a dependency on the devcontainer CLI project which is maintained by the specification owners. When you choose to open a container using the devcontainer.json file, Zed just calls the devcontainer up command provided by this CLI.

Using this reference implementation allowed us to get the fundamental experience up and running quickly, and most importantly, in your hands without a massive up-front investment. It also means that Zed will continue to easily support any changes to the specification, so long as the reference implementation stays up to date.

That being said, there are some drawbacks to this approach. Firstly, port tunneling is limited in this context due to a known issue; so, while Zed will support the appPort property in devcontainer.json, it will not yet support forwardPorts (again, see the specification for more details).

Secondly, using the reference implementation means that Zed cannot yet define its own extensions in devcontainer.json. This is an open-ended part of the specification defined in the customizations property, because it is by definition tool-specific: VS Code will define its extensions differently than Zed, for instance. Still, being able to predefine Zed extensions will be crucial to taking this feature to the next level: while vanilla Dev Containers provide the ability to make your environment consistent, defining extensions will allow other users to make their Zed experience consistent as well. Speaking of, this is a good time to transition to our plans for the future!

What's next

There's still lots more to do with Dev Containers in Zed. First, addressing your feedback on the existing UX is key, so please get in touch if you have thoughts on what we've shipped thus far!

But additionally, there are a few features coming which will make this a more thorough experience:

The ability to define a Dev Container spec: Aside from letting you take a valid devcontainer.json file and turn it into a running container, we want to make it possible for you to define your own JSON, with a little help from Zed: fetching features and templates from known repositories, expanding templated values, and generally making it easier to create and edit this file.
Extensions: As mentioned above, there is no way to define a number of desired Zed extensions in devcontainer.json. This will definitely be added, and in doing so, we'll likely break our dependency with the CLI tool in favor of an internal implementation. This should make the whole experience a little more seamless and less brittle.
forwardPorts: With an in-house implementation, we'll look to support the forwardPorts property of the specification, which will allow for more sophisticated remote-to-host communication during the development process.

We're excited to have this v1 out and to see what you think of it!

Check out similar blogs from the Zed team.