Create overview.mdx by lavanya-gunreddi · Pull Request #864 · runpod/docs

lavanya-gunreddi · 2026-09-28T17:51:04Z

No description provided.

mintlify · 2026-09-28T17:51:08Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
runpod-docs	🟢 Ready	View Preview	Oct 26, 2026, 3:38 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

prestwick

Handful of suggested changes and nitpicks.

prestwick · 2026-10-09T15:07:03Z

+    In the GPU picker, find the **External compute** section. It lists the GPU types available on your organization's online machines. Select the GPU you want.
+  </Step>
+  <Step title="Configure and deploy">
+    Configure the rest of the Pod the way you normally would, including the template, storage, and environment variables. Then click **Deploy**.


Is there a doc with the workflow we reference that can be linked here?

prestwick · 2026-10-09T15:08:05Z

+
+## How placement works
+
+When you deploy on external compute, Runpod places the Pod on one of your organization's online machines that matches the GPU you selected. Pods deployed on your machines stay within your organization. Other Runpod customers can't deploy on them.


Suggested change

When you deploy on external compute, Runpod places the Pod on one of your organization's online machines that matches the GPU you selected. Pods deployed on your machines stay within your organization. Other Runpod customers can't deploy on them.

When you deploy on external compute, Runpod places the Pod on one of your organization's online machines that matches the GPU you selected. Pods deployed on your machines stay within your organization. Other Runpod customers can't deploy to them.

prestwick · 2026-10-09T15:59:32Z

+    In the Runpod console, go to **Resources → External compute** and click **Add compute**.
+  </Step>
+  <Step title="Describe the machine">
+    Select your machine type, such as an on-prem server, enter a name for the machine, and click **Next**.


In my testing there was some limitation on the hostnames we could give the machines. Our generated hostnames use underscores by default, and I had to change those to hyphens to get things working. I'm going to escalate this to Mike and Audry, but this may require some mention.

From https://man7.org/linux/man-pages/man7/hostname.7.html

Each element of the hostname must be from 1 to 63 characters long
and the entire hostname, including the dots, can be at most 253
characters long. Valid characters for hostnames are ASCII(7)
letters from a to z, the digits from 0 to 9, and the hyphen (-).
A hostname may not start nor end with a hyphen.

prestwick · 2026-10-09T16:07:20Z

+
+This page covers the most common problems when you connect and use external compute, and what to do about each.
+
+## Verification failed


There is also a "verification timed out" state. When I was testing this was because sshd wasn't listening on all interfaces and therefore ~~Nebula~~ the Runpod control plane couldn't make an SSH connection to the machine. This likely could be generalized as the machine couldn't complete the network connection to the control plane.

Added a “Verification timed out” section, written generally as Runpod not being able to reach the machine, with the sshd fix as the first step. Also added it to the status table on the setup page.

audryhsu · 2026-10-15T15:32:54Z

+
+## Requirements
+
+Runpod Hybrid Cloud is available to organizations only. The Runpod team must enable External Compute for your org account before the feature appears in your console. [Contact us](https://www.runpod.io/everywhere) to get set up.


the term 'external compute' is being debated and might be changed, fyi. TBD if it changes to 'private compute'.

I’ll hold off on this for the time being until a decision is made.

audryhsu · 2026-10-15T15:33:09Z

+## How it works
+
+<Steps>
+  <Step title="Add your machine">


'machine' vs 'compute

Let's use compute. Lines up better with the planned terminology changes.

See my comment below for the usage of "machine" and "compute"

audryhsu · 2026-10-15T15:34:06Z

+  <Step title="Add your machine">
+    In the console, go to **Resources → External compute** and click **Add compute**. Select your machine type (on-prem server, AWS EC2 instance, or any cloud VM), give it a name, and click **Next**.
+  </Step>
+  <Step title="Install the host agent">


will need to align on how to refer to "host agent". i think we might refer to it as "Runpod agent" preferrably, but let's get a decision memorialized then we can mass update. @prestwick

Current recommendation is Host connector.

@Promptless replace “host agent” with “host connector” in all four files under hybrid-cloud/

audryhsu · 2026-10-15T15:34:19Z

+    In the console, go to **Resources → External compute** and click **Add compute**. Select your machine type (on-prem server, AWS EC2 instance, or any cloud VM), give it a name, and click **Next**.
+  </Step>
+  <Step title="Install the host agent">
+    Copy the install command that appears and paste it into an SSH session on your machine. This installs the Runpod host agent, a small program that connects your machine to Runpod over an outbound-only encrypted connection. No inbound ports are opened. Set your public and private IPs, open the required firewall ports, then reboot. For full instructions, see [Set up external compute](/hybrid-cloud/setup).


'machine' vs 'compute'

@audryhsu here’s how I plan to update the docs. Let me know if you have any concerns before i make.

• Compute: anywhere the reader is working in the Runpod console, like adding it, naming it, checking its status or deploying to it. This matches the console labels (“External compute,” “Add compute”).
• Machine: only when the reader is working on the server itself, like SSHing in, running the install command or rebooting.

For example, “Click Add compute and give your compute a name,” but “Open an SSH session on your machine and run the install command.”

I’ll apply this across all the pages if you agree.

I like this guidance.

audryhsu · 2026-10-15T15:39:30Z

+
+- An [organization](/organizations/orgs-overview) with external compute enabled. During alpha, the Runpod team enables this for you.
+- An organization role that allows you to add compute. See [Roles](/organizations/org-roles).
+- A single machine with at least one GPU. Multi-node machines connected by InfiniBand or a similar fabric aren't supported yet.


@maltmanRP you good with this language? thinking we could leave it more open ended like "talk to runpod" if they need multinode usecase.

I like this phrasing. Customer feedback on this will help with prioritization.

@Promtpless - change it to "A single machine with at least one GPU. If you need multi-node support, such as machines connected by InfiniBand or a similar fabric, contact the Runpod team to discuss your use case."

audryhsu · 2026-10-15T15:44:09Z

+2. Check that the machine can make outbound connections to the internet.
+3. Confirm that you rebooted the machine after you configured networking.
+
+## Machine stuck in verification in progress


fyi @prestwick it will timeout after 15 min and retry once, then if that fails again, will end in Verification failed state. don't know if we need to expose all the nitty gritty but we have sweepers and retries that will make sure these land in some terminal state after ~30 minutes.

Good to know. Maybe we state here that verification should complete within 30 minutes. Otherwise contact support.

@Promptless Verification usually completes within 30 minutes. If a machine stays in Verification in progress for longer than that, contact Runpod support with the machine name, and they'll help you complete verification.

prestwick · 2026-10-20T14:07:32Z

+2. Check that the machine can make outbound connections to the internet.
+3. Confirm that you rebooted the machine after you configured networking.
+
+## Machine stuck in verification in progress


Good to know. Maybe we state here that verification should complete within 30 minutes. Otherwise contact support.

jiayi-runpod · 2026-10-20T21:00:30Z

+
+## Get started
+
+Runpod Hybrid Cloud is available to early customers, and the Runpod team works with you directly to set up your machines. [Request a demo](https://www.runpod.io/hybrid-cloud) to get started.


Maybe nitpick, I feel this "early customers" reads a little bit wierd.

How about "Runpod Hybrid Cloud is in alpha and available to select customers, ..."?

@Promptless change it to "Runpod Hybrid Cloud is in alpha and available to select customers, and the Runpod team works with you directly to set up your machines."

promptless · 2026-10-22T19:02:57Z

Got it. I'll update the Hybrid Cloud overview with your wording and reply here once the change is on this branch.

promptless · 2026-10-22T19:04:05Z

@lavanya-gunreddi Done. The "Get started" section of hybrid-cloud/overview.mdx now reads: "Runpod Hybrid Cloud is in alpha and available to select customers, and the Runpod team works with you directly to set up your machines." The "Request a demo" link after it is unchanged.

Commit: e515f3e

promptless · 2026-10-22T19:48:55Z

Got it — I will add the note that verification usually completes within 30 minutes, with guidance to contact Runpod support if a machine stays in Verification in progress longer. I will push the change to this branch and reply here when it is ready.

promptless · 2026-10-22T19:49:54Z

I picked up your second request too. I am adding the 30-minute verification note to the Verification in progress section of hybrid-cloud/troubleshooting.mdx. I am also applying the suggested change to the inbound network row in setup.mdx so it reads TCP 10000 and 20000. Both changes are going to this branch, and I will reply when they are pushed.

promptless · 2026-10-22T19:50:38Z

@lavanya-gunreddi I pushed both changes to lg-hybrid-cloud in commit 40e1daf.

The "Machine stuck in verification in progress" section of hybrid-cloud/troubleshooting.mdx now uses your wording about the 30-minute limit and contacting Runpod support. In the requirements table in hybrid-cloud/setup.mdx, I applied prestwick's suggestion, so the inbound network row now reads "TCP 10000 and 20000."

The new paragraph links to the Get help section, which tells readers to contact their Runpod onboarding contact rather than Runpod support. You may want to make the two match. I left Get help unchanged.

Commit: 40e1daf

promptless · 2026-10-22T20:13:26Z

Got it. I'll replace "host agent" with "host connector" in the four files under hybrid-cloud/ and reply here when the change is ready.

promptless · 2026-10-22T20:14:22Z

I replaced "host agent" with "host connector" under hybrid-cloud/ and pushed the change to lg-hybrid-cloud as commit 7ff7d8b.

There were 13 replacements across three files:

overview.mdx: 4, including a step title.
setup.mdx: 8, including the page description, a step title, and the status table.
troubleshooting.mdx: 1.

deploy.mdx didn't contain "host agent", so I left it unchanged. A case-insensitive search of hybrid-cloud/ now finds no "host agent", "host-agent", or "hostagent".

lavanya-gunreddi · 2026-10-26T15:31:25Z

@promptess replace host agent with host controller through out the files

lavanya-gunreddi · 2026-10-26T15:33:13Z

@Promptless "Machine" vs. "compute"
Use "compute" when the reader is working in the Runpod console (adding, naming, checking status, deploying). Keep "machine" only for the physical server (SSH, install command, reboot, networking, disks, drivers). Specifically:

overview.mdx: step title "Add your machine" → "Add your compute"; "Give your machine a name" → "Give your compute a name"; "the machine's status changes to Online" → "your compute's status changes to Online"; "External Compute" → "external compute" in the Requirements section and "External Compute section" → "External compute section".
setup.mdx: "The machine is then online" → "Your compute is then online"; heading "## Add your machine" → "## Add your compute"; step title "Describe the machine" → "Name your compute"; "Enter a name for the machine" → "Enter a name for your compute"; "in the machine name" → "in the name"; heading "## Machine statuses" → "## Compute statuses"; "Each machine on the External compute page" → "Each entry on the External compute page"; in the status table, use "compute" for Pending install, Pending verification, Online, and Under maintenance; "Machines you add are visible only to your organization. They aren't listed…" → "Compute you add is visible only to your organization. It isn't listed…".
deploy.mdx: use "compute" instead of "machine(s)" throughout (description, intro, Requirements, steps, How placement works, Track usage). "Other Runpod customers can't deploy to them" → "can't deploy to it".
troubleshooting.mdx: description "machines stuck in a status" → "compute stuck in a status"; "When a machine's status is" → "When your compute's status is"; "open the machine on the External compute page" → "open your compute on…"; headings "Machine stuck in pending install", "Machine stuck in verification in progress", "Machine doesn't appear in the GPU picker" → start with "Compute" instead of "Machine"; in the GPU picker section use "your compute's GPU", "your compute's status", "Compute in any other status", "owns the compute", "every GPU on your compute"; in Get help, "the machine name" → "the compute name".
Leave "machine" in sentences about SSH, the install command, rebooting, networking, /etc/fstab, Docker disk, and NVIDIA drivers.

promptless · 2026-10-26T15:33:49Z

@lavanya-gunreddi Got it: switch "machine" to "compute" wherever the reader works in the Runpod console across overview.mdx, setup.mdx, deploy.mdx, and troubleshooting.mdx, and keep "machine" for the physical server. I'm applying your list to this PR and will reply here when the update is pushed.

lavanya-gunreddi · 2026-10-26T15:35:01Z

@Promptless troubleshooting.mdx, "Compute stuck in verification in progress"
Replace the paragraph with:
"Verification usually completes within 30 minutes. If your compute stays in Verification in progress for longer than that, contact Runpod support with the compute name, and they'll help you complete verification."

lavanya-gunreddi · 2026-10-26T15:35:14Z

@Promptless setup.mdx, Requirements
Replace "A single machine with at least one GPU. Multi-node machines connected by InfiniBand or a similar fabric aren't supported yet." with:
"A single machine with at least one GPU. If you need multi-node support, such as machines connected by InfiniBand or a similar fabric, contact the Runpod team to discuss your use case."

lavanya-gunreddi · 2026-10-26T15:35:30Z

@Promptless troubleshooting.mdx, Get help
Replace "contact your Runpod onboarding contact" with "contact Runpod support".

promptless · 2026-10-26T15:35:31Z

@lavanya-gunreddi I pushed the "machine" to "compute" changes to overview.mdx, setup.mdx, deploy.mdx, and troubleshooting.mdx, following your list.

I made three small changes your list didn't cover:

In deploy.mdx, the requirement reads "External compute with the Online status" instead of "At least one compute with…".
In the troubleshooting verification section, "If a machine stays in Verification in progress" became "If your compute stays…".
In that same section, "with the machine name" became "with the compute name".

"Machine" stays wherever the text means the physical server: SSH, the install command, the host connector connection, networking, rebooting, /etc/fstab and Docker disk, and NVIDIA drivers. It also stays in the status table rows for Verification timed out and Offline, and in "any Runpod machine" and "set up your machines" in the overview. Tell me if you want any of those switched too.

I'm working on your two newer edits, the verification paragraph in troubleshooting.mdx and the multi-node sentence in setup.mdx, and will reply on each when they're pushed.

One question: an earlier comment of yours asked to replace "host agent" with "host controller", but it was addressed to @promptess (a typo), so I never received it. The pages say "host connector". Do you want them changed to "host controller"?

Commit: fea7ae0

promptless · 2026-10-26T15:36:24Z

@lavanya-gunreddi Your three newer edits are done, and the changes are pushed to this PR:

In setup.mdx Requirements, the multi-node sentence uses your wording, including the link to contact the Runpod team.
In the Get help section of troubleshooting.mdx, "contact your Runpod onboarding contact" is now "contact Runpod support".
The paragraph under "Compute stuck in verification in progress" already matched your text after the terminology update, so it needed no change.

Commit: b667040

lavanya-gunreddi · 2026-10-26T15:37:16Z

@Promptless yes change host connector to host controller

promptless · 2026-10-26T15:37:48Z

Got it: I will change "host connector" to "host controller" in this PR. I will reply here once the update is pushed.

promptless · 2026-10-26T15:38:47Z

@lavanya-gunreddi Done: "host connector" is changed to "host controller" in all the Hybrid Cloud pages on this PR.

The change covers 13 places: 4 in overview.mdx (including the "Install the host controller" step title), 8 in setup.mdx (the page description, the install step and the status table), and 1 in troubleshooting.mdx. A search of hybrid-cloud/ and docs.json finds no remaining "connector" or "host agent".

Commit: ed495cd

Create overview.mdx

2f8e2a2

mintlify Bot deployed to staging September 28, 2026 17:51

View deployment

lavanya-gunreddi added 2 commits September 28, 2026 14:10

Create setup.mdx

40851fd

Create deploy.mdx

7f62029

mintlify Bot deployed to staging September 28, 2026 18:11

View deployment

Create troubleshooting.mdx

a9c8829

mintlify Bot deployed to staging September 28, 2026 18:11

View deployment

Update docs.json

20c43ac

mintlify Bot deployed to staging September 28, 2026 18:13

View deployment

prestwick requested changes Oct 9, 2026

View reviewed changes

Merge branch 'main' into lg-hybrid-cloud

42e12d5

mintlify Bot deployed to staging October 19, 2026 17:03

View deployment

Update overview.mdx

973c7e3

mintlify Bot deployed to staging October 19, 2026 18:36

View deployment

Update setup.mdx

9c2d4ab

mintlify Bot deployed to staging October 19, 2026 18:39

View deployment

Update troubleshooting.mdx

0129f46

mintlify Bot deployed to staging October 19, 2026 18:46

View deployment

Update deploy.mdx

79f6ef7

mintlify Bot deployed to staging October 19, 2026 18:48

View deployment

Merge branch 'main' into lg-hybrid-cloud

80bdc38

mintlify Bot deployed to staging October 19, 2026 19:07

View deployment

audryhsu reviewed Oct 19, 2026

View reviewed changes

prestwick previously approved these changes Oct 20, 2026

View reviewed changes

jiayi-runpod reviewed Oct 20, 2026

View reviewed changes

Update Hybrid Cloud availability wording in overview

e515f3e

promptless Bot dismissed prestwick’s stale review via e515f3e October 22, 2026 19:03

mintlify Bot deployed to staging October 22, 2026 19:04

View deployment

Add verification timing note and correct inbound ports for Hybrid Cloud

40e1daf

mintlify Bot deployed to staging October 22, 2026 19:50

View deployment

Rename "host agent" to "host connector" in Hybrid Cloud docs

7ff7d8b

mintlify Bot deployed to staging October 22, 2026 20:14

View deployment

Use "compute" for console references in Hybrid Cloud docs

fea7ae0

mintlify Bot deployed to staging October 26, 2026 15:35

View deployment

lavanya-gunreddi and others added 2 commits October 26, 2026 11:35

Merge branch 'main' into lg-hybrid-cloud

38a3261

Apply reviewer wording for multi-node support and Get help contact

b667040

mintlify Bot deployed to staging October 26, 2026 15:36

View deployment

Rename "host connector" to "host controller" in Hybrid Cloud docs

ed495cd

mintlify Bot deployed to staging October 26, 2026 15:38

View deployment


		## How placement works

		When you deploy on external compute, Runpod places the Pod on one of your organization's online machines that matches the GPU you selected. Pods deployed on your machines stay within your organization. Other Runpod customers can't deploy on them.


		This page covers the most common problems when you connect and use external compute, and what to do about each.

		## Verification failed


		## Requirements

		Runpod Hybrid Cloud is available to organizations only. The Runpod team must enable External Compute for your org account before the feature appears in your console. [Contact us](https://www.runpod.io/everywhere) to get set up.


		## Get started

		Runpod Hybrid Cloud is available to early customers, and the Runpod team works with you directly to set up your machines. [Request a demo](https://www.runpod.io/hybrid-cloud) to get started.

Conversation

lavanya-gunreddi commented Sep 28, 2026

Uh oh!

mintlify Bot commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

prestwick left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

promptless Bot commented Oct 22, 2026

Uh oh!

promptless Bot commented Oct 22, 2026

Uh oh!

promptless Bot commented Oct 22, 2026

Uh oh!

promptless Bot commented Oct 22, 2026

Uh oh!

promptless Bot commented Oct 22, 2026

mintlify Bot commented Sep 28, 2026 •

edited

Loading

promptless Bot commented Oct 26, 2026 •

edited

Loading