devcon

A lightweight CLI that wraps devcontainers with automatic port forwarding.

VS Code's devcontainer support is great, and some alternative editors do support devcontainers... but if you use a different editor like vim there's nothing that handles port forwarding to your localhost for you. The @devcontainers/cli can start containers, but any ports your app listens on inside the container aren't accessible from the host. You end up manually running docker exec or some socat shenanigans to get at them or even needing to put the docker contain in network: host mode.

devcon fixes this. It starts your devcontainer, deploys a small agent inside it, and automatically detects and forwards ports as services start and stop — just like VS Code does, but from any terminal.

Install

bun install -g @contour-3d/devcon

Requires Bun and Docker.

For the best experience, ensure that your user is added to the docker group if it isn't already.

sudo usermod -aG docker $USER

Usage

devcon up                  # start container + port forwarding
devcon shell               # open a shell in the container
devcon exec -- bun test    # run a command in the container
devcon ports               # list forwarded ports
devcon down                # stop everything

Run from a directory with a .devcontainer/devcontainer.json. Ports listed in forwardPorts are forwarded immediately; any other ports are picked up automatically as services bind to them.

How it works

devcon up does the following:

1. Starts the devcontainer via @devcontainers/cli
2. Deploys a bundled agent script into the container
3. The agent monitors /proc/net/tcp and /proc/net/tcp6 for listening sockets
4. When a new port appears, devcon opens a local TCP listener on the same port and bridges traffic into the container via docker exec
5. When a port disappears, the local listener is torn down

Port forwarding supports both IPv4 and IPv6 services inside the container. The forwardPorts config also accepts "host:container" mappings, and portsAttributes with onAutoForward: "ignore" is respected.

Only programs running as subprocesses of the docker exec shell will have their port binding automatically forwarded- if you need access to a port binded in a systemd process for example you can specify the used ports in forwardPorts.