Pasting images straight into a devcontainer

I’ve written previously about devcontainer-bridge, the small Rust tool I built to bring automatic port forwarding and host browser opening to terminal-based devcontainer workflows.

Since then, another piece of friction has kept bothering me: screenshots.

My development environment runs inside a devcontainer, usually with tmux and an AI coding agent. The agent can work with images, but the clipboard belongs to my Mac. Getting a screenshot across that boundary meant saving it somewhere, copying it into the container, finding the path, and then passing that path to the agent.

None of those steps are difficult. Together, they interrupt the flow often enough to be annoying.

So dbr can now do this:

dbr paste

Which produces something like:

/home/vscode/.cache/dbr/paste/image-a1b2c3/clipboard.png

That’s it. The image on the host clipboard is now a private file inside the devcontainer, ready for any tool that accepts a local image path.

How it works

dbr paste connects to the existing host daemon and requests the current clipboard image. The host reads the clipboard, validates the result, and transfers the original PNG or JPEG bytes into the container.

Each image is written to a unique directory beneath ~/.cache/dbr/paste. On Unix, the directory is created with 0700 permissions and the image with 0600 permissions. Partial or failed transfers do not leave image files behind.

On macOS, dbr can also convert TIFF clipboard data to PNG. This matters because copying pixels from applications such as Preview does not always put a PNG representation on the pasteboard.

Copying an image file in Finder is different again. Finder provides both a file reference and rendered image data. My first implementation happily selected the rendered data and transferred Finder’s generic PNG file icon rather than the contents of the file.

Technically an image. Not quite the image I wanted.

The current implementation detects a single PNG or JPEG file copied in Finder, reads the file itself, and validates its byte signature before transferring it. Unsupported files, multiple selections, unreadable files and oversized images fail explicitly rather than silently falling back to the icon.

Using it from tmux

The command can also insert the resulting path directly into a tmux pane:

bind-key V run-shell -b 'dbr paste --tmux-target "#{pane_id}" >/dev/null'

With that in my container’s tmux configuration, I can copy a screenshot on the Mac, press my tmux prefix followed by Shift-V, and the quoted image path appears at the cursor.

It deliberately does not press Enter. The receiving application decides how to use the path.

This has been particularly useful when working with coding agents. I can capture a broken interface, paste the image path into the conversation, and continue without leaving the terminal.

Enabling clipboard access

Clipboard sharing is opt-in. On the host, add this to ~/.config/dbr/config.toml:

[clipboard]
enabled = true

Then restart the daemon:

dbr restart

Install or upgrade the host binary with:

curl -fsSL \
  https://github.com/bradleybeddoes/devcontainer-bridge/releases/latest/download/install.sh \
  | bash

The host and container must share the existing dbr authentication token. Clipboard transfers are limited to 20 MiB and only one transfer is allowed at a time.

There is no continuous clipboard synchronisation and no support for arbitrary clipboard contents. The client must explicitly request an image each time.

There is also no per-request confirmation on the host. Any client with the host token can request a supported clipboard image while the feature is enabled. Transfers use the bridge’s existing unencrypted TCP connection, so its ports should remain within the trusted host and container network.

Successful images remain in the container until removed. This is intentional—the receiving tool may need the file after dbr paste exits—but it means the cache should be cleaned up when those images are no longer required.

A small feature with an outsized effect

Clipboard image transfer is not a large feature, but it removes another boundary between the host and the development environment.

Ports appear on the host automatically. Browser links open in the right place. Unix sockets can cross the container boundary. Now screenshots and copied image files can move in the other direction with one command.

The best developer tooling often works like this. It does not introduce a new workflow. It removes the awkward parts from the workflow you already have.

The paste functionality is available in the latest devcontainer-bridge release. The full setup, tmux integration and security details are in the clipboard guide.

If you’re using devcontainers from the terminal, I’d genuinely appreciate the feedback. Issues and contributions are welcome on GitHub.