> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Cloud Agents

export const GuideFlow = ({id, title, frameSize = "wide"}) => {
  const paddingBottom = frameSize === "small" ? "calc(56.23387790197765% + 10px)" : frameSize === "medium" ? "calc(56.23387790197765% + 47px)" : "calc(62.004487658937926% + 47px)";
  return <div style={{
    position: "relative",
    paddingBottom,
    height: 0
  }}>
			<iframe id={id} title={title || "Step-by-step guide"} src={`https://app.guideflow.com/embed/${id}`} width="100%" height="100%" style={{
    overflow: "hidden",
    position: "absolute",
    border: "none"
  }} allow="clipboard-read; clipboard-write" allowFullScreen />
		</div>;
};

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

export const CursorCloudAgentsDiagram = () => {
  const NamespaceMark = ({size = 32}) => <img className="ns-diagram-mark" src="/docs/favicon.svg" alt="" width={size} height={size} />;
  const CursorMark = ({size = 32}) => <span className="ns-diagram-mark ns-diagram-mark-cursor" style={{
    width: size,
    height: size
  }}>
			<svg width={Math.round(size * 0.58)} height={Math.round(size * 0.58)} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
				<path d="M11.503.131 1.891 5.678a.84.84 0 0 0-.42.726v11.188c0 .3.162.575.42.724l9.609 5.55a1 1 0 0 0 .998 0l9.61-5.55a.84.84 0 0 0 .42-.724V6.404a.84.84 0 0 0-.42-.726L12.497.131a1.01 1.01 0 0 0-.996 0M2.657 6.338h18.55c.263 0 .43.287.297.515L12.23 22.918c-.062.107-.229.064-.229-.06V12.335a.59.59 0 0 0-.295-.51l-9.11-5.257c-.109-.063-.064-.23.061-.23" />
			</svg>
		</span>;
  const ControlPlaneMark = ({size = 32}) => <span className="ns-diagram-mark ns-diagram-mark-control" style={{
    width: size,
    height: size
  }}>
			<svg width={Math.round(size * 0.55)} height={Math.round(size * 0.55)} viewBox="0 0 24 24" fill="none" aria-hidden="true">
				<circle cx="12" cy="12" r="2.5" fill="currentColor" />
				<circle cx="5" cy="5" r="1.5" fill="currentColor" />
				<circle cx="19" cy="5" r="1.5" fill="currentColor" />
				<circle cx="5" cy="19" r="1.5" fill="currentColor" />
				<circle cx="19" cy="19" r="1.5" fill="currentColor" />
				<path d="M12 12L5 5M12 12l7-7M12 12l-7 7M12 12l7 7" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" />
			</svg>
		</span>;
  const TerminalMark = ({size = 32}) => <span className="ns-diagram-mark ns-diagram-mark-terminal" style={{
    width: size,
    height: size
  }}>
			<svg width={Math.round(size * 0.55)} height={Math.round(size * 0.55)} viewBox="0 0 24 24" fill="none" aria-hidden="true">
				<rect x="3" y="4" width="18" height="14" rx="2" stroke="currentColor" strokeWidth="1.8" />
				<path d="M7 9l3 3-3 3M13 15h4" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
			</svg>
		</span>;
  const DiagramCard = ({mark, label, sublabel, brand = false}) => <div className={`ns-diagram-card${brand ? " ns-diagram-card-brand" : ""}`}>
			{mark}
			<div className="ns-diagram-card-copy">
				<span className="ns-diagram-card-label">{label}</span>
				<span className="ns-diagram-card-sublabel">{sublabel}</span>
			</div>
		</div>;
  const ZoneHeader = ({owner, mark}) => <div className="ns-diagram-zone-header">
			{mark}
			<span>{owner}</span>
		</div>;
  const Zone = ({brand = false, children}) => <section className={`ns-diagram-zone${brand ? " ns-diagram-zone-brand" : ""}`}>
			{children}
		</section>;
  const SessionZone = ({label}) => <Zone>
			<ZoneHeader owner="Cursor" mark={<CursorMark size={14} />} />
			<DiagramCard mark={<CursorMark size={36} />} label={`Session ${label}`} sublabel="Model, planning & context" />
		</Zone>;
  const CursorConnector = ({management = false}) => <div className={`ns-devin-connector${management ? " ns-devin-management-connector" : ""}`} aria-hidden="true">
			<div className="ns-devin-connector-line" />
			<div className="ns-diagram-arrow-down" />
			<span>{management ? "launch & manage" : <>tool calls<br />& events</>}</span>
		</div>;
  const ControlPlanePill = () => <div className="ns-control-plane-pill">
			<ControlPlaneMark size={18} />
			<span>Namespace control plane</span>
		</div>;
  const MobileSessionLane = ({label}) => <div className="ns-devin-mobile-lane">
			<SessionZone label={label} />
			<div className="ns-devin-mobile-connectors">
				<CursorConnector />
				<CursorConnector management />
			</div>
			<Zone brand>
				<ZoneHeader owner="Namespace" mark={<NamespaceMark size={14} />} />
				<ControlPlanePill />
				<DiagramCard brand mark={<TerminalMark size={36} />} label={`Devbox ${label}`} sublabel="Runs the Cursor worker" />
			</Zone>
		</div>;
  const label = "Every Cursor Cloud Agent session connects to its own isolated Namespace Devbox while the Namespace control plane launches and manages the environments.";
  return <figure className="ns-diagram not-prose" role="img" aria-label={label}>
			<div className="ns-diagram-grid-background" aria-hidden="true" />
			<div className="ns-diagram-content">
				<div className="ns-devin-desktop-layout">
					<div className="ns-devin-sessions">
						<SessionZone label="A" />
						<SessionZone label="B" />
					</div>
					<div className="ns-devin-connectors">
						<div><CursorConnector /><CursorConnector management /></div>
						<div><CursorConnector /><CursorConnector management /></div>
					</div>
					<Zone brand>
						<ZoneHeader owner="Namespace" mark={<NamespaceMark size={14} />} />
						<ControlPlanePill />
						<div className="ns-devin-devboxes">
							<DiagramCard brand mark={<TerminalMark size={36} />} label="Devbox A" sublabel="Runs the Cursor worker" />
							<DiagramCard brand mark={<TerminalMark size={36} />} label="Devbox B" sublabel="Runs the Cursor worker" />
						</div>
					</Zone>
				</div>
				<div className="ns-devin-mobile-layout">
					<MobileSessionLane label="A" />
					<MobileSessionLane label="B" />
				</div>
			</div>
			<figcaption className="ns-diagram-caption">{label}</figcaption>
		</figure>;
};

[Cursor](https://cursor.com) Cloud Agents are natively supported on Namespace Devboxes. When you start a new agent session, Namespace provisions a fresh Devbox for it. Cursor's agent loop, including inference and planning, continues to run in Cursor's cloud, while terminal commands, file edits, git operations, and repository access happen on the Devbox.

## Getting Started

### Requirements

Before you start you need the following pieces:

* [Namespace account](https://cloud.namespace.so)
* Cursor account on the [Enterprise plan](https://cursor.com/enterprise)

<Steps titleSize="h3">
  <Step id="configure-cursor-cloud-agents" title={<span>Configure Cursor Cloud Agents</span>}>
    Open the [Cloud Agents dashboard](https://cursor.com/dashboard/cloud-agents) in Cursor, and enable the following:

    * **Team Pools**
    * **GitHub token minting**

    <CenteredImage width={1200} alt="Cloud Agents dashboard" src="/docs/images/devboxes/cursor/cursor-cloud-agents-configure.webp" />

    <Note>The above Cursor settings are team admin controls, so if you are not an admin on your Cursor team, ask one to enable them.</Note>
  </Step>

  <Step id="create-cursor-service-token" title={<span>Create a Cursor service account token</span>}>
    In the Cursor dashboard, open [**Settings** > **API Keys** > **Service Accounts**](https://cursor.com/dashboard/api), and press **New Service Account**. Enter a name, and optionally a description, then press **Create**.

    Copy the generated key.

    <CenteredImage width={1200} alt="Creating a service account in the Cursor dashboard" src="/docs/images/devboxes/cursor/cursor-cloud-agents-create-service-account.webp" />

    <Note>
      **Repository Access** needs to be set to **All repositories from team's connected Git providers**.

      Pool workers authenticate with a Cursor [service account](https://cursor.com/docs/account/enterprise/service-accounts) API key. Personal, team, and organization API keys cannot start pool workers.
    </Note>
  </Step>

  <Step id="create-devbox-blueprint" title={<span>Create Devbox blueprint</span>}>
    Next, create a Devbox blueprint, which defines the environment that Cursor Cloud Agents run in.

    Navigate to the [Devbox Blueprints](https://cloud.namespace.so/workspace/devboxes/blueprints) page, press the **+ New Blueprint** button, select **Cursor** and press **Configure**.

    Configure the following:

    * `Name` - the name of your blueprint, which only appears in the Devbox list, not in the Cursor UI
    * `Cursor` - press **Configure** in the Cursor tile, fill in the following, and press **Save**:
      * `Service token` - the service account key you created in the previous step
      * `Pool name` - the name of the worker pool
    * `Operating system` - pick between Linux or macOS, along with the image or macOS version
    * `Instance size` - to select the vCPUs and RAM your tasks need

    Once everything is in place, press **Create Blueprint**.

    <Note>
      The **Pool name** appears in the Cursor UI under **Remote Machines** once the blueprint is saved.

      See [blueprint configuration](/docs/devbox/blueprint#additional-configuration) for more configuration options.
    </Note>

    <GuideFlow id="ok8v58mfxp" title="Guide: Create a Cursor Cloud Agents blueprint" frameSize="wide" />
  </Step>

  <Step id="running-the-agent" title={<span>Running the agent</span>}>
    And now, you can run a Cursor Cloud Agent on a Devbox.

    Start a [New Chat](https://cursor.com/agents), expand the menu next to the <Icon icon="cloud" /> icon, and select your Devbox **Pool name** from the list of **Remote Machines**.

    <CenteredImage width={1200} alt="Select Devbox Pool name" src="/docs/images/devboxes/cursor/cursor-cloud-agents-select-pool-name.webp" />

    Select the repository you want to work on, and give your agent a task, like:

    ```text wrap Agent Prompt theme={null}
    What is the operating system you are running on?
    ```

    <CenteredImage width={1200} alt="What is the OS output" src="/docs/images/devboxes/cursor/cursor-cloud-agents-example.webp" />
  </Step>
</Steps>

## How it works

<CursorCloudAgentsDiagram />

Cursor handles orchestration: the agent loop, planning, context management, and inference all run in Cursor's cloud.

Namespace handles execution: shell commands, file edits, repository access, builds, and test runs all happen on a Devbox.

When the session ends, the worker exits and Namespace tears the Devbox down, so each session gets a clean environment and nothing is left running afterwards.