`convex dev` prompts for URL and admin key in dev mode (devcontainer)

[iamfj]

Running pnpm convex dev inside a DevContainer starts successfully, but opening the provided dashboard URL (http://127.0.0.1:6790/?d=anonymous-xyz) prompts me for a URL and admin key — which should not be required in dev mode.

When running the exact same setup outside the DevContainer (on my host machine), everything works as expected: the dashboard opens normally and no authentication prompt appears.

Terminal Output:

$ pnpm convex dev
✔ Downloaded Convex backend binary
✔ Downloaded Convex dashboard
✔ Started running a deployment locally at http://127.0.0.1:3210 and saved its name as CONVEX_DEPLOYMENT to .env.local
Run `npx convex login` at any time to create an account and link this deployment.

Write your Convex functions in convex/
Give us feedback at https://convex.dev/community or support@convex.dev
View the Convex dashboard at http://127.0.0.1:6790/?d=anonymous-xyz

✔ 17:08:44 Convex functions ready! (163.61ms)

Dev Container Setup:

Here’s a minimal version of my .devcontainer/devcontainer.json:

{
  "name": "node",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
  "mounts": [
    "source=${localEnv:HOME}/.convex,target=/home/node/.convex,type=bind,consistency=cached"
  ],
  "remoteUser": "node",
  "remoteEnv": {
    "CONVEX_TMPDIR": "/home/node/.convex-tmp"
  }
}

What I’ve Tried:

• Deleted the .convex/ directory and re-initialized the project
• Recreated the project multiple times
• Restarted the dev container and host
• Tried both logged in and logged out (pnpm convex logout)
• Verified it works as expected outside of the container

Expected Behavior:

In dev mode, the Convex dashboard should open without requiring credentials or an admin key.

System Info:

• Environment: DevContainer (Docker)
• Image: mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm
• Docker version: 27.5.1
• pnpm version: 10.10.0
• convex version: 1.23.0

Screenshot:

[nipunn1313]

You definitely do need an admin key to run local dashboard. Check instrucs here on how to generate an admin key

https://github.com/get-convex/convex-backend/tree/main/self-hosted#docker-configuration

I'm not familiar with DevContainers - you'll have to figure out specifics there, but when I do the supported instructions of docker compose up with docker compose exec backend ./generate_admin_key.sh - things work.

[iamfj]

Hey @nipunn1313,

first of all, thanks a lot for your quick and helpful response — really appreciate it!

You’re absolutely right that an admin key is needed. In fact, the key does get generated — I can confirm it exists under ~/.convex/.... That’s exactly why I’m a bit puzzled: when running pnpm convex dev outside the DevContainer, everything works perfectly. But inside the DevContainer, the dashboard prompts for a key, even though the setup should be the same.

My assumption is that the issue lies in where Convex stores and expects the admin key and deployment state when running convex dev. If I understand that correctly, I can make sure the relevant directories are properly mounted into the container — not just for persistence, but also to mirror the expected runtime behavior.

Do you have insights into:

• where exactly convex dev stores and reads its state and keys (e.g., admin key, deployment metadata)?
• how it resolves paths?

If I can figure that out, I’d love to create a proper DevContainer config and maybe even contribute a quick guide or snippet to the docs. I imagine other users running Convex in containerized dev environments would benefit from this too.

Thanks again!

[nipunn1313]

Hmm good questions!

The CLI with self-hosting / dockerized uses information from .env.local https://github.com/get-convex/convex-backend/tree/main/self-hosted#docker-configuration - which is in your project directory. CLI is expected to run from the project directory and it will read from .env.local to get the self hosted url and self hosted admin key.

The CLI can also read/write to ~/.convex, but I don't think it's required for self-hosting, but you can try fiddling with that too to see if it makes a difference

The dashboard itself reads from local storage - you have to punch the admin key in manually in the UI and then it'll save to local storage. You can look at details here

convex-backend/npm-packages/dashboard-self-hosted/src/pages/_app.tsx

Line 36 in 22a93fc

function App({

Good luck! Would def appreciate a guide if you get something working. I'm still not really familiar with what DevContainers are, so it's hard for me to help, but I'm sure the community would appreciate it. I'll check it out if you get something working.

[iamfj]

What a hell of a debugging session! 😅

After your message, I went full detective mode.

First, I completely disassembled the convex dev command from the cli package to trace how it starts the local servers and dashboard, and to figure out why the exact same setup works outside the DevContainer but not inside. Spoiler: the environments were basically identical. No smoking gun there.

Then I looked at the dashboard itself, which was the missing puzzle piece. Your hint to the _app.tsx file was gold:

convex-backend/npm-packages/dashboard-self-hosted/src/pages/_app.tsx

Lines 308 to 314 in 22a93fc

	if (listDeploymentsApiPort) {
	if (!Number.isNaN(parseInt(listDeploymentsApiPort))) {
	setListDeploymentsApiUrl(
	normalizeUrl(`http://127.0.0.1:${listDeploymentsApiPort}`),
	);
	}
	} else {

Those lines check whether a local API server is available. If it is — boom, you’re signed in. If it’s not — welcome to the sign-in screen.

Back to the browser. From inside my DevContainer, I could access the dashboard at localhost:6790 — so the UI loaded fine. But it couldn’t reach the local API server that runs at localhost:6791. That check failed silently, and I landed on the "Enter URL + Admin Key" screen every time.

🕵️‍♂️ Final culprit? Port forwarding in VSCode DevContainers.

VSCode usually forwards container ports to the host automatically. Starting a dev server on port 3000? Boom, it’s forwarded. But not always. Ports 3210 and 6790 were forwarded fine — that’s why I saw the dashboard UI.

Port 6791, though, was not. And that’s the one the dashboard uses for the local dev healthcheck.

Solution:

Explicitly add the three needed ports to .devcontainer/devcontainer.json:

  "forwardPorts": [3210, 6790, 6791]

Once that’s in place, the dashboard works just as beautifully as it does outside the container. No more auth screen!

---

Would you be interested in a short docs PR or guide snippet for getting Convex working smoothly inside DevContainers? Could save the next poor soul a couple of hours of head-scratching. 😄

[nipunn1313]

Yeah! Put a README self-hosted/devcontainers and that'll be great