Environment links in server settings (optionally opened in the in-app browser)

[rgembalik]

Context

We auto-provision dev environments from user repositories that match our company template. Each environment runs T3 Code server, and the T3 Code client is the main way developers work with it. Opening the environment is opening T3 Code.

Each environment also has public URLs:

• the frontend app
• the Convex backend
• a browser-based VS Code

The provisioner knows these URLs when it creates the environment, but T3 Code has no place to show them.

Problem

• URLs live outside T3 Code. Developers have to find environment URLs elsewhere, even though T3 Code is how they open the environment.
• previewUrl on project actions doesn't cover this:
  • a URL can only be part of an action, so a plain link needs a dummy command
  • it only works on the desktop build, not when connecting to a remote T3 Code server
  • inside a remote environment, localhost:3000 isn't the address users reach. Only the provisioner knows the public URL.
• t3.json isn't a good fit. It's committed to the user's repo, and these URLs change with every environment.
• No good way to view the running app next to T3 Code. There's no in-app view on web/remote clients. Browser features like Chrome split view could fill the gap, but they need a real link to open, and T3 Code has nowhere to show one.

Proposal (minimal)

Add a project-scoped server setting, e.g. defaultProjectLinks, alongside the existing defaultProjectScripts. It would be settable for the whole environment and per project via projectSettingsOverrides, following the same pattern as other project-scoped settings:

// server settings.json
{
  "defaultProjectLinks": [
    { "name": "VS Code", "url": "https://code.dev-123.example.com" }
  ],
  "projectSettingsOverrides": {
    "<projectId>": {
      "defaultProjectLinks": [
        { "name": "Frontend", "url": "https://app.dev-123.example.com", "openInPreview": true },
        { "name": "Convex dashboard", "url": "https://convex.dev-123.example.com" }
      ]
    }
  }
}

• Links show in the project UI (e.g. next to the actions menu). They don't run anything.
• openInPreview: true opens the link in the in-app browser. Otherwise it opens in a new browser tab.
• The remote server supplies the links, so every connected client sees the right public URLs. No setup per user, and no changes to the user's repo.
• Provisioners already write environment defaults to this file, so no new tooling is needed.

Possible later additions (not required for a first version):

• t3 CLI commands to manage links (similar to t3 theme set / t3 project add)
• a links field in t3.json as a project default, using the same fallback order as other file-backed settings
• an editor in the settings UI, like the one for project actions

Render links as real <a href> elements

However links are configured, they should render as real anchors (<a href="…">), not as buttons that open a URL from a click handler.

Why it matters:

• Browser features work. Users can drag a link into Chrome split view (or a similar feature in other browsers), open it in a new tab or window with middle-click / Ctrl/Cmd+click, copy the link address, or bookmark it. That gives web/remote users a working side-by-side setup today, even without an in-app browser.
• Accessibility. Screen readers announce it as a link and show where it goes. Link lists and rotor navigation include it, and keyboard behavior matches what users expect from a link. A button that navigates tells assistive technology it's a button when it actually goes somewhere.
• It matches what it is. A configured URL is navigation, not a command.

How it fits with openInPreview:

• A plain click can still open the in-app browser (desktop) by handling the click and preventing the default.
• Modifier clicks, middle-click, dragging, and the context menu keep the browser's normal link behavior, because the href is still there.
• Where the in-app browser isn't available, the anchor just opens the URL (e.g. target="_blank" with rel="noopener noreferrer").

Closest existing functionality: URL-only actions

The nearest thing T3 Code has today is project actions with previewUrl / autoOpenPreview. Much of what this proposal needs is already there:

• UI: the actions menu and the settings editor for actions
• Storage: environment-wide defaultProjectScripts plus per-project overrides in server settings
• Similar options: name, icon, a URL, and a choice about opening it in the in-app browser
• Similar behavior: a configured URL opened from the project UI

So a smaller-change alternative would be to extend actions:

1. Make command optional when previewUrl is set. Clicking such an action only opens the URL and doesn't start a terminal.
2. Allow previewUrl on remote/web clients. If the in-app browser isn't available, open the URL in a new browser tab instead of ignoring it.
3. Render URL-only actions as <a href> in the actions menu, as described above, so split view, new-tab, and accessibility work the same way.

// server settings.json — URL-only actions (alternative)
{
  "projectSettingsOverrides": {
    "<projectId>": {
      "defaultProjectScripts": [
        { "id": "frontend", "name": "Frontend", "icon": "globe",
          "previewUrl": "https://app.dev-123.example.com", "autoOpenPreview": true },
        { "id": "vscode", "name": "VS Code", "icon": "code",
          "previewUrl": "https://code.dev-123.example.com" }
      ]
    }
  }
}

Caveats:

• The word "action" may not fit. Opening a link isn't really an action, and mixing commands with links in one menu may confuse users. The UI could show URL-only actions differently, e.g. with a link icon or in their own group.
• Some action options don't apply to links, such as runOnWorktreeCreate, async, and keyboard shortcuts that run a command.
• autoOpenPreview means "open when the script starts". For a URL-only action it would have to mean "open in the in-app browser when clicked".
• Menu items are usually buttons. URL-only items would need to render as links inside the menu, which is another reason a separate links area may fit better.

Either approach solves our use case. A separate links setting is cleaner, while URL-only actions reuse more of what already exists.

Alternatives considered

• Dummy actions with previewUrl (today): desktop-only, needs a fake command, clutters the actions menu, and isn't a real link.
• Writing URLs into t3.json at provisioning time: leaves a modified, environment-specific file in the user's checkout.
• Communicating URLs outside T3 Code (dashboards, READMEs, chat): works, but splits the workflow away from the tool developers actually open.

Relation to existing discussions

• [Feature]: Add an authenticated browser preview gateway for served web #6847 proposes an authenticated preview gateway (proxy) for the served web client. This proposal complements it: our URLs are already public, so declared links work without a proxy. Links also cover pages that aren't previews, like a browser-based VS Code or the Convex dashboard. With real <a href> links, users also get a side-by-side setup through their browser's split view before any gateway exists.
• [Mobile] Add Browser Preview for remote web development via T3 Connect #14119 asks for browser preview on mobile through remote connections. It's the same gap, seen from mobile.

Open questions

• Could openInPreview (or previewUrl on URL-only actions) work in web/remote clients for links that are already public (e.g. as an iframe), even before a gateway like [Feature]: Add an authenticated browser preview gateway for served web #6847 exists? If not, is falling back to a new tab acceptable?
• Separate links setting or URL-only actions: which fits the product direction better?
• Should project actions be able to point to a link (e.g. previewLink: "Frontend") instead of repeating a previewUrl?
• Is defaultProjectLinks the right name, or would projectLinks fit better since links aren't really "defaults"?

Disclosure

Yes, the proposal is written by my Opus, but I do solemnly swear I've read it and authored the idea itself down to the details. I just didn't want to miss any implementation gaps.