feat: better handling of RUNLOOP_BASE_URL (#216)

Author: jrvb-rl

.github/workflows/e2e.yml

@@ -37,5 +37,5 @@ jobs:
       - name: Run e2e smoke tests
         env:
           RUNLOOP_API_KEY: ${{ inputs.environment == 'prod' && secrets.RUNLOOP_SMOKETEST_PROD_API_KEY || secrets.RUNLOOP_SMOKETEST_DEV_API_KEY }}
-          RUNLOOP_ENV: ${{ inputs.environment }}
+          RUNLOOP_BASE_URL: ${{ inputs.environment == 'prod' && 'https://api.runloop.ai' || 'https://api.runloop.pro' }}
         run: pnpm run test:e2e

CLAUDE_SETUP.md

@@ -133,9 +133,9 @@ Press Ctrl+C to stop it.
 
 ## Advanced Configuration
 
-### Using Development Environment
+### Custom API endpoint
 
-If you want to connect to Runloop's development environment:
+To connect to a non-default Runloop deployment, set `RUNLOOP_BASE_URL` to the full API URL (must be `https://api.<domain>`):
 
 ```json
 {
@@ -144,13 +144,15 @@ If you want to connect to Runloop's development environment:
       "command": "rli",
       "args": ["mcp", "start"],
       "env": {
-        "RUNLOOP_ENV": "dev"
+        "RUNLOOP_BASE_URL": "https://api.runloop.pro"
       }
     }
   }
 }
 ```
 
+See the repository [README](README.md) **Setup → Custom API endpoint (`RUNLOOP_BASE_URL`)** for the hostname table.
+
 ### Using a Specific Path
 
 If `rli` isn't in your PATH, you can specify the full path:

MCP_COMMANDS.md

@@ -65,9 +65,9 @@ When you run `rli mcp install`, it creates this configuration in your Claude Des
 }
 ```
 
-### With Environment Variables
+### Custom API endpoint
 
-To use the development environment:
+To point MCP at a different deployment, set `RUNLOOP_BASE_URL` (must be `https://api.<domain>`):
 
 ```json
 {
@@ -76,13 +76,15 @@ To use the development environment:
       "command": "rli",
       "args": ["mcp", "start"],
       "env": {
-        "RUNLOOP_ENV": "dev"
+        "RUNLOOP_BASE_URL": "https://api.runloop.pro"
       }
     }
   }
 }
 ```
 
+See [README.md](README.md) (Setup → Custom API endpoint) for the hostname table.
+
 ## Available Tools
 
 Once configured, Claude can use these tools:

MCP_README.md

@@ -102,9 +102,6 @@ If you prefer to configure manually, add this to your Claude configuration file:
     "runloop": {
       "command": "rli",
       "args": ["mcp", "start"],
-      "env": {
-        "RUNLOOP_ENV": "prod"
-      }
     }
   }
 }
@@ -151,8 +148,8 @@ Claude will use the MCP tools to interact with your Runloop account and provide
 
 ## Environment Variables
 
-- `RUNLOOP_ENV` - Set to `dev` for development environment, `prod` (or leave unset) for production
-- API key is read from the CLI configuration (~/.config/rli/config.json)
+- `RUNLOOP_BASE_URL` — Optional. Full API URL of the form `https://api.<domain>` (e.g. `https://api.runloop.pro`). Defaults to `https://api.runloop.ai`. See [README](README.md) **Setup → Custom API endpoint (`RUNLOOP_BASE_URL`)**.
+- API key is read from the CLI configuration (`~/.runloop/config.json`)
 
 ## Troubleshooting
 

README.md

@@ -46,14 +46,31 @@ pnpm add -g @runloop/rl-cli
 
 ## Setup
 
-Configure your API key:
+### API key
 
 ```bash
 export RUNLOOP_API_KEY=your_api_key_here
 ```
 
 Get your API key from [https://runloop.ai/settings](https://runloop.ai/settings)
 
+### Custom API endpoint (`RUNLOOP_BASE_URL`, optional)
+
+By default the CLI and MCP server connect to `https://api.runloop.ai`. To use a different deployment, set `RUNLOOP_BASE_URL` to the full API URL:
+
+```bash
+export RUNLOOP_BASE_URL=https://api.runloop.pro
+```
+
+The URL must be of the form `https://api.<domain>`. The CLI derives other service hostnames from the domain portion:
+
+| Service  | Host |
+|----------|------|
+| API      | `https://api.<domain>` (the value of `RUNLOOP_BASE_URL`) |
+| Platform | `https://platform.<domain>` |
+| SSH      | `ssh.<domain>:443` |
+| Tunnels  | `tunnel.<domain>` |
+
 ## Usage
 
 ### TUI (Interactive Mode)

src/cli.ts

@@ -3,7 +3,7 @@
 import { exitAlternateScreenBuffer } from "./utils/screen.js";
 import { processUtils } from "./utils/processUtils.js";
 import { createProgram } from "./utils/commands.js";
-import { getApiKeyErrorMessage } from "./utils/config.js";
+import { getApiKeyErrorMessage, checkBaseDomain } from "./utils/config.js";
 
 // Global Ctrl+C handler to ensure it always exits
 processUtils.on("SIGINT", () => {
@@ -21,6 +21,8 @@ const program = createProgram();
   const { initializeTheme } = await import("./utils/theme.js");
   await initializeTheme();
 
+  checkBaseDomain();
+
   // Check if API key is configured (except for mcp commands)
   const args = process.argv.slice(2);
   if (!process.env.RUNLOOP_API_KEY) {

src/components/Breadcrumb.tsx

@@ -1,6 +1,7 @@
 import React from "react";
 import { Box, Text, useStdout } from "ink";
 import { colors } from "../utils/theme.js";
+import { runloopBaseDomain } from "../utils/config.js";
 import { UpdateNotification } from "./UpdateNotification.js";
 
 export interface BreadcrumbItem {
@@ -38,8 +39,8 @@ export const Breadcrumb = ({
   showVersionCheck = false,
   compactMode: compactModeProp,
 }: BreadcrumbProps) => {
-  const env = process.env.RUNLOOP_ENV?.toLowerCase();
-  const isDevEnvironment = env === "dev";
+  const baseDomain = runloopBaseDomain();
+  const isNonDefaultDomain = baseDomain !== "runloop.ai";
   const { stdout } = useStdout();
 
   const [terminalWidth, setTerminalWidth] = React.useState(() =>
@@ -109,10 +110,10 @@ export const Breadcrumb = ({
           <Text color={colors.primary} bold>
             rl
           </Text>
-          {isDevEnvironment && mode !== "minimal" && (
-            <Text color={colors.error} bold>
+          {isNonDefaultDomain && mode !== "minimal" && (
+            <Text color={colors.warning} bold>
               {" "}
-              (dev)
+              ({baseDomain})
             </Text>
           )}
           {displayItems.length > 0 && <Text color={colors.textDim}> › </Text>}

src/components/DevboxActionsMenu.tsx

@@ -12,6 +12,7 @@ import { ConfirmationPrompt } from "./ConfirmationPrompt.js";
 import { colors } from "../utils/theme.js";
 import { openInBrowser } from "../utils/browser.js";
 import { copyToClipboard } from "../utils/clipboard.js";
+import { sshGatewayHostname } from "../utils/config.js";
 import { useViewportHeight } from "../hooks/useViewportHeight.js";
 import { useNavigation } from "../store/navigationStore.js";
 import { useExitOnCtrlC } from "../hooks/useExitOnCtrlC.js";
@@ -661,8 +662,7 @@ export const DevboxActionsMenu = ({
 
           const sshUser =
             devbox.launch_parameters?.user_parameters?.username || "user";
-          const env = process.env.RUNLOOP_ENV?.toLowerCase();
-          const sshHost = env === "dev" ? "ssh.runloop.pro" : "ssh.runloop.ai";
+          const sshHost = sshGatewayHostname();
           // macOS openssl doesn't support -verify_quiet, use compatible flags
           // servername should be %h (target hostname) - SSH will replace %h with the actual hostname from the SSH command
           // This matches the reference implementation where servername is the target hostname

src/components/DevboxDetailPage.tsx

@@ -12,7 +12,7 @@ import {
   type DetailSection,
   type ResourceOperation,
 } from "./ResourceDetailPage.js";
-import { getDevboxUrl, getDevboxTunnelUrlPattern } from "../utils/url.js";
+import { getDevboxUrl, getTunnelUrl } from "../utils/url.js";
 import { colors } from "../utils/theme.js";
 import { formatTimeAgo } from "../utils/time.js";
 import { getMcpConfig } from "../services/mcpConfigService.js";
@@ -339,7 +339,7 @@ export const DevboxDetailPage = ({ devbox, onBack }: DevboxDetailPageProps) => {
     if (devbox.tunnel && devbox.tunnel.tunnel_key) {
       const tunnelKey = devbox.tunnel.tunnel_key;
       const authMode = devbox.tunnel.auth_mode;
-      const tunnelUrl = getDevboxTunnelUrlPattern(tunnelKey);
+      const tunnelUrl = getTunnelUrl("{port}", tunnelKey);
 
       detailFields.push({
         label: "Tunnel",
@@ -651,7 +651,7 @@ export const DevboxDetailPage = ({ devbox, onBack }: DevboxDetailPageProps) => {
         </Text>,
       );
 
-      const tunnelUrl = getDevboxTunnelUrlPattern(devbox.tunnel.tunnel_key);
+      const tunnelUrl = getTunnelUrl("{port}", devbox.tunnel.tunnel_key);
       lines.push(
         <Text key="tunnel-url" color={colors.success}>
           {" "}

src/components/HomeBaseUrlText.tsx

@@ -0,0 +1,16 @@
+import React from "react";
+import { Text } from "ink";
+import { runloopBaseDomain } from "../utils/config.js";
+import { colors } from "../utils/theme.js";
+
+/** Shows the active domain in the home footer when it differs from the default. */
+export function HomeBaseUrlText() {
+  const baseDomain = React.useMemo(() => runloopBaseDomain(), []);
+  if (baseDomain === "runloop.ai") return null;
+  return (
+    <Text color={colors.textDim} dimColor>
+      {"\n"}
+      Domain: {baseDomain}
+    </Text>
+  );
+}