Hey everyone!
In the last few years, I’ve been working as a software developer mainly in remote environments (mostly with Docker based workspaces), so I’ve come into contact with many workspace provisioners.
I really like this way to work, everything is reproducible and problems due to the development environment are minimized. On the other hand many workspace provisioners that I’ve tried are very difficult to use and the defining the structure of workspace is not quite easy and sometimes it takes a long time to learn and this is not ideal for small teams.
So a question came to mind: why this provisioners don’t use standard tools and formats to define the structure of a workspace?
That idea eventually became Codebox, a side project that has now reached its first open-source beta.
In this article, I want to share what Codebox is, why I decided to build it, how it works, and what’s coming next.
What is Codebox?
Codebox is a self-hosted distributed provider of remote development environments.
What does that mean? With Codebox you can define the resources and the structure of a workspace using standard formats like Docker Compose or Devcontainers. Moreover it provides connection to the workspaces through an SSH connection and the possibility to expose to everyone or with restrictions HTTP services running inside the containers.
Codebox consists in four main parts:
1. A central server with web UI
This is where you can view, create and manage workspaces. The UI provides also an editor for workspace templates and admin tools to manage the server and the connected services.
2. Runners that host and manage the workspaces
Here’s where Codebox’s architecture becomes flexible. Workspaces are not managed directly from the server. Instead, you register runners, each capable of running different type of running one or more workspace types. This leads to several benefits including the fact that the workload can be divided between multiple machines.
Runners must be able to reach the main server, but not the vice versa. In this way you can register runners from multiple locations without opening ports on routers.
3. Agents running inside containers
Agents are running inside workspaces, they provide the connections to the containers. They have an integrated SSH server. The SSH connection is tunneled over Web Sockets, in this way you don’t need to open other ports on your router.
4. A CLI for connecting via SSH (tunneled over HTTP)
The CLI is a component to install on users’ PCs. It provides an SSH proxy to connect via an SSH connection to the workspaces. You can also use the official VS Code extension that wraps the CLI and provides an easy way to connect to workspaces.
Current Status: First Open-Source Beta
This release is very much a beta.
There are bugs, rough edges, missing features, and probably a few design choices that will evolve over time.
In fact, I expect major changes as I gather feedback and see how people use (or break!) the system.
Still, the core architecture is stable enough to share, and I’m excited to see where it goes.
You can find it here:
Main Server
https://github.com/davidebianchi03/codebox
https://gitlab.com/codebox4073715/codebox
Runner
https://gitlab.com/codebox4073715/codebox-docker-runner
Agent
https://gitlab.com/codebox4073715/codebox-agent
CLI
https://gitlab.com/codebox4073715/codebox-cli
VS Code Extension
https://gitlab.com/codebox4073715/codebox-vscode-extension
What’s next?
I have plenty of ideas for new features I want to add to Codebox, but before moving forward, I’d like to make the current codebase stronger and more reliable.
If you want to support the project
If the idea resonates with you or you find the project interesting, feel free to leave a star on the GitHub repository.
It helps with visibility and motivates me to keep iterating — but it’s completely optional.
Final Thoughts
Codebox started as a personal exploration into remote development tooling, but it’s slowly becoming something I hope others might find useful as well.
It’s simple, open-source, self-hosted, and built on familiar standards — and I think there’s a place for that in the growing landscape of dev environments.
If you give it a try, I’d love to hear what you think.
Top comments (0)