Docked

PyCharm-style remote interpreter for Docker Compose projects, keeping VS Code 100% local (your git, keybindings and other extensions are untouched). Use your container as the interpreter/runtime for introspection, debugging and tests — without dev containers or "Attach to Running Container".

Multi-language by design. One extension that adapts to the project's language via pluggable providers. Python is implemented today; PHP and Node are planned (see FUTURE.md). The language is auto-detected per workspace (override with docked.language), so you install once and it does the right thing in each project — no enabling/disabling per repo.

All features live behind the Docked status bar button.

Connect / Disconnect

• Connect syncs the mirror and selects the container interpreter for the workspace, remembering whichever interpreter you had before.
• Disconnect restores that previous interpreter (the mirror stays cached on disk).

The status bar shows the state: $(debug-disconnect) Docked when disconnected, $(server-environment) Docked when connected, $(warning) Docked when connected but the container's packages drifted.

1. Interpreter introspection (mirror)

For Python, replicates PyCharm's "remote sources": copies site-packages from the container into a local venv built with a matching local Python (pyenv or system), then selects it. Pylance gets full God-level introspection against the exact library versions of the image. A pip freeze hash makes re-syncs a no-op when nothing changed.

On window open it compares the container's current packages against the last sync; if they changed it flags the status bar and offers a one-click Resync, so introspection never silently drifts from the running container.

Requires a local Python with the same major.minor as the container (pyenv install 3.13).

For languages whose deps live inside the project (Node node_modules, PHP vendor/, usually bind-mounted), this step is largely unnecessary — the language server already sees them locally.

2. Debug in container

Zero changes to the project: installs the debug backend (debugpy for Python) into the running container on the fly. The debuggee runs debugpy --listen 127.0.0.1:<port> --wait-for-client inside the container and the extension port-forwards a free host port to it over docker compose exec stdio (a kubectl-port-forward equivalent — no compose port mapping needed). VS Code then attaches with a standard connect. remoteRoot is auto-detected from the container's bind mounts. Stopping the session tears down the tunnel and the container process.

Configure commands per project in .vscode/settings.json:

"docked.debugConfigs": {
  "runserver": "manage.py runserver 0.0.0.0:8000 --noreload",
  "worker": "manage.py run_worker"
}

3. Tests in container (native play buttons)

A Test Controller that discovers tests with the runner inside the container (pytest for Python) and runs/debugs them there, with native gutter play buttons (per test, class and file) and Test Explorer integration. Failures are mapped back to local files; assertion Expected:/Actual: blocks are rendered as a native VS Code diff.

Caveat: cancelling a run kills the local docker exec client; the runner may keep running inside the container until it finishes.

See FUTURE.md for planned work (more language providers, C-extension stub generation, packaging).

Settings

Install (no marketplace)

Plain JavaScript with zero dependencies — clone and symlink the checkout into the VS Code extensions dir:

git clone git@github.com:verabravo/docked.git
ln -sfn "$PWD/docked" \
  ~/.vscode/extensions/verabravo.docked-0.1.1

Reload VS Code afterwards (Cmd+Shift+P → "Reload Window").