[Feature]: Devcontainer integration

[ryanhiebert]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

Not sure

Problem or use case

I prefer to code in a devcontainer. It makes sure that I have a running environment with all my needed dependencies and tools ready to go. Further still, in VS Code, I'm able to clone a GitHub repository into a docker volume, significantly reducing the trade-offs from mounting a Mac filesystem, and totally isolating the devcontainer from the host filesystem. This allows things like bun and uv to work much more effectively than with bind mounts.

But no harness or harness interface supports helping me manage devcontainers for projects. I think it would be a massive up-level for working with multiple agents if each one was working in a separate, isolated devcontainer, in a totally separate git clone, ready to have all of its dependencies manipulated, other apps installed if needed, and every backing service, like postgresql and redis, able to be given a dedicated clean environment that no other.

Proposed solution

When starting a new agent, I'd like to be able to choose a git or GitHub repository to clone into a docker volume, and when cloned to have it allow me to choose which devcontainer to launch (multiple devcontainers are permitted in the same repo) against that volume as the mount for the app working directory.

Why this matters

This deep isolation can make agents much more independent and capable, because they will have a non-conflicting environment that has all fresh dependencies. It can also pave a clearer path for fully-operation cloud agents.

Smallest useful scope

A smaller useful scope might be to have tools that can be devcontainer-aware. But that sounds like a harness problem, so likely outside the scope of T3 Code.

It feels like the isolated docker volume + devcontainer set up may be the minimal scope here.

Alternatives considered

Worktrees give some reasonable part of the benefit, but fall short of the isolation that devcontainers give. Worktrees clash with each other (branches can only be check out in one worktree). You can install packages separately, but typically won't have isolated database, etc, so the agent isn't starting from a clean environment. Plus, they are running on the host, so if the application is not developed to run cross-platform with the host OS (most devcontainers are Linux, many hosts are Mac), you end up needing to solve that problem before you can use them effectively.

Risks or tradeoffs

The biggest hurdles I see are:

• Figuring out how to create and clone a repo into a docker volume, including figuring out what sources (local git, GitHub) are appropriate.
• Figuring out how to mount the repo volume to the devcontainer, as well as mount other mount points from the local filesystem, like user config paths.
• Ensuring that the agent is installed and available in the devcontainer
• Connecting to the agent in the devcontainer, rather than on the host

Examples or references

• VS Code Devcontainer Clone into a named container volume is a good example of the isolation paradigm.

Contribution

• I would be open to helping implement this.

[RoySalisbury]

I'm with you. I use devcontainers for all my development. This way I can also use github codespaces when needed for quick issues or even using the vscode.dev site.

I used to clone the repo into a named volume like you indicate, but found that more of a hassle than a benifit. If I needed to fix a devcontner ar access a file I could just get it direct form the local FS.

One thing I have done however is installed opencode directly into the devcontiner and have it setup to share a port to the host. Then from the host I can do a docker exec on the devcontainer and start the opencode server (could do the same for t3 code I expect). Now from the host I can connect opencode to the shared port of the devcontainer. So opencode now sees and operates inside the devcontiner.

Now, if this could all be automated by something .. like ...

clone a repo to the FS
run the harness and tell it to start/build the devcontainer and automatically hook into that ...

Its the same as having vscode do it, but without running vscode.

[nocnokneo]

We run T3 Code against dev containers from laptops to Linux box on a tailnet with repos whose toolchain only exists in the container. What works is the inverse of "connect the host server to a container": run the T3 server inside the dev container, since the server is already T3's execution boundary: terminals, git, worktrees and agent processes all execute wherever t3 serve runs. No host↔container path translation, no docker exec shims around the agent binary.

One long-lived container per repository (not per worktree), brought up with the devcontainer CLI:

devcontainer up --workspace-folder "$repo" \
  --mount "type=bind,source=$HOME/.t3/$name,target=$HOME/.t3/$name" \
  --remote-env "T3CODE_HOME=$HOME/.t3/$name"
devcontainer exec --workspace-folder "$repo" --remote-env "T3CODE_HOME=$HOME/.t3/$name" \
  npx --yes t3@latest serve --tailscale-serve --no-browser

A few things that make it work:

• Paths identical inside and out. The repo is mounted at its host path ("workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind"), and so is T3CODE_HOME. T3's worktrees live at $T3CODE_HOME/worktrees/<repo>/<branch>, and a git worktree's .git file holds an absolute path back to the main clone, so with matching paths the worktrees resolve on both sides and host tools can open them.
• One T3CODE_HOME per repo, because each container runs its own server and two servers must not share a state.sqlite.
• The container is its own tailnet node (ghcr.io/tailscale/codespace/tailscale feature), so --tailscale-serve gives an HTTPS URL per repo with no port publishing and no SSH tunnel. Gotcha: T3 runs tailscale serve as the container user, so that user must be the tailscaled operator (tailscale up --operator=$USER, or tailscale set --operator=$USER; note tailscale up resets prefs it isn't given). Otherwise T3 only logs Failed to configure Tailscale Serve … permission-denied and quietly serves on loopback.

The rough edges we hit, in case they're useful as small fixes:

1. t3 serve --tailscale-serve prints its connection string, pairing URL and QR code for http://localhost:3773, which is unreachable from the device that needs to pair. Printing the Tailscale Serve URL (it takes the same token) would remove a real stumble.
2. Opening a pairing URL in a browser consumes the one-time token; the desktop app then reports "The environment credential is invalid" with no hint that a new token is one t3 pair away.

The feature: a dev container feature that runs the T3 server

The remaining manual step is starting the server, and the dev container spec already has the right hook: a feature can declare an entrypoint that runs whenever the container starts (the Tailscale feature works exactly this way). A t3code-server feature would:

• install a pinned t3 (Node is a feature dependency, node-pty needs a C toolchain — both easy to declare);
• start t3 serve from its entrypoint as the container's remoteUser, honouring T3CODE_HOME, T3CODE_HOST/T3CODE_PORT and T3CODE_TAILSCALE_SERVE from containerEnv, logging to $T3CODE_HOME;
• optionally publish with Tailscale Serve when a tailscale binary is present and the node is logged in, else listen on the configured port;
• write the pairing URL somewhere the host can read it (the mounted T3CODE_HOME), so devcontainer up is the whole bring-up.

That leaves the host-side tooling at devcontainer up --additional-features '{"ghcr.io/…/t3code-server":{}}', which anyone can adopt without touching a shared devcontainer.json, and the desktop app connecting to the printed URL. For the "clone into a Docker volume with fresh services per agent" scenario in the original post, the same feature applies unchanged — the container is different, the server-in-container shape is not.

In this meantime, this little agent-env script (needs a better name) does the job