> ## 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.

# Claude Managed 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 ManagedAgentsDiagram = () => {
  const NamespaceMark = ({size = 32}) => <img className="ns-diagram-mark" src="/docs/favicon.svg" alt="" width={size} height={size} />;
  const AnthropicMark = ({size = 32}) => <span className="ns-diagram-mark ns-diagram-mark-anthropic" style={{
    width: size,
    height: size
  }}>
			<svg width={Math.round(size * 0.62)} height={Math.round(size * 0.62)} viewBox="0 0 24 24" aria-hidden="true">
				<path clipRule="evenodd" fillRule="evenodd" d="M20.998 10.949H24v3.102h-3v3.028h-1.487V20H18v-2.921h-1.487V20H15v-2.921H9V20H7.488v-2.921H6V20H4.487v-2.921H3V14.05H0V10.95h3V5h17.998v5.949zM6 10.949h1.488V8.102H6v2.847zm10.51 0H18V8.102h-1.49v2.847z" fill="currentColor" />
			</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 ManagedConnector = () => <div className="ns-managed-connector" aria-hidden="true">
			<span>tool_use</span>
			<div className="ns-managed-connector-path">
				<div className="ns-managed-connector-line" />
				<div className="ns-managed-connector-arrow" />
			</div>
		</div>;
  const MiniConnector = () => <div className="ns-mini-connector" aria-hidden="true">
			<div />
			<span />
		</div>;
  const label = "Anthropic runs the agent loop and sends tool calls through the Namespace control plane to an isolated Devbox.";
  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-managed-layout">
					<Zone>
						<ZoneHeader owner="Anthropic" mark={<AnthropicMark size={14} />} />
						<div className="ns-diagram-zone-center">
							<DiagramCard mark={<AnthropicMark size={36} />} label="Agent loop" sublabel="Model, planning & tool calls" />
						</div>
					</Zone>
					<ManagedConnector />
					<Zone brand>
						<ZoneHeader owner="Namespace" mark={<NamespaceMark size={14} />} />
						<DiagramCard brand mark={<ControlPlaneMark size={36} />} label="Namespace control plane" sublabel="Routes work to a fresh Devbox" />
						<MiniConnector />
						<DiagramCard brand mark={<TerminalMark size={36} />} label="Devbox" sublabel="Isolated VM, per session" />
					</Zone>
				</div>
			</div>
			<figcaption className="ns-diagram-caption">{label}</figcaption>
		</figure>;
};

Claude Managed Agents are natively supported on Namespace Devboxes. Each Claude Agent session
is backed by its own ephemeral Namespace Devbox. When you start a new session, Namespace provisions
a fresh Devbox for it.

## What are Devboxes?

Devboxes are high-performance environments which are best-in-class for code related workflows, like builds
and tests. Our Docker based environments provide you and your agents with the same toolchains that you'd use
in CI (Docker, Bazel, Gradle, etc.). You also get lifecycle management that helps keep costs under control
without sacrificing performance.

## How it works

<ManagedAgentsDiagram />

Anthropic handles orchestration: the model, the agent loop, context management, and error recovery. Namespace
handles execution: shell commands, file operations, tool calls, builds, test runs, etc.

## Prep

Before you start you will need the following pieces:

* [Claude Console account](https://platform.claude.com/)
* [Namespace account](https://cloud.namespace.so)

### Devbox CLI

If you are new to Devboxes, you can get started by installing the Devbox CLI.

<Steps titleSize="h3">
  <Step id="install-the-devbox-cli" title={<span>Install the Devbox CLI</span>}>
    Install the Devbox CLI to create and manage devboxes:

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        curl -fsSL get.namespace.so/devbox/install.sh | bash
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        curl -fsSL get.namespace.so/devbox/install.sh | bash
        ```
      </Tab>

      <Tab title="Windows">
        Run the following in PowerShell:

        ```bash theme={null}
        irm https://get.namespace.so/devbox/install.ps1 | iex
        ```

        You may need to restart your terminal after installation for the `devbox` command to be available on your `PATH`.

        An [OpenSSH client](https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse) is also required. Most modern Windows installations include this by default.
      </Tab>
    </Tabs>
  </Step>

  <Step id="authenticate-with-namespace" title={<span>Authenticate with Namespace</span>}>
    Authenticate with Namespace using the Devbox CLI:

    ```bash theme={null}
    devbox login
    ```

    This opens your browser to complete authentication. Once logged in, you're ready to create and manage devboxes.
  </Step>
</Steps>

## Setup Managed Claude Agent with Devbox

<Steps titleSize="h3">
  <Step title="Start the setup process">
    Run the following command to start the setup process, and provide your Anthropic API key when prompted:

    ```bash theme={null}
    devbox claude managed-agents setup-environment
    ```

    <CenteredImage width={900} alt="Provide Anthropic API Key" src="/docs/images/integrations/devbox-create-cli-1-done.png" />
  </Step>

  <Step title="Generate Service Key">
    The Devbox CLI will automatically create a new environment in the Anthropic console for you.
    Now you need to generate a new service key for the environment.

    <CenteredImage width={900} alt="New Claude Managed Agent Environment" src="/docs/images/integrations/devbox-create-cli-2.png" />

    Open the link provided by the CLI (which will take you to the newly created environment), to generate a new service key for the environment, and **paste the key back into the CLI**.

    <GuideFlow id="dkdz6llagr" title="Interactive guide" frameSize="medium" />
  </Step>

  <Step title="Configure Webhook">
    Next, you need to configure a webhook in the **Anthropic console**,
    to allow Anthropic to send events to Namespace with instructions for the agent to execute.

    <CenteredImage width={900} alt="Configure Webhook" src="/docs/images/integrations/devbox-create-cli-3.png" />

    To help you with this step, the CLI provides you with `workspace webhooks URL` and `namespace webhook URL`.

    Head over to `workspace webhooks URL` and start the process to create a webhook:

    * use the `namespace webhook URL` as the endpoint URL for the webhook.
    * make sure to enable all `Session lifecycle events`
    * and copy the generated `webhook secret`.

    <GuideFlow id="xrg30j5h1k" title="Interactive guide" frameSize="medium" />

    Then copy the webhook secret back into the CLI to complete the setup.

    <CenteredImage width={900} alt="Copy Webhook Secret" src="/docs/images/integrations/devbox-create-cli-3-done.png" />
  </Step>
</Steps>

## Running the agent

Now, that you have a working Managed Agent setup with Namespace Devbox, you just need to create a Claude agent, and start using it to complete your tasks.

<Steps titleSize="h3">
  <Step title="Create a Claude Agent">
    Create a new agent in the [Antropic console](https://platform.claude.com/workspaces/default/agents).

    Here is an example configuration for a Claude agent that can connect to Namespace Devbox Agent Runner:

    ```json theme={null}
    {
      "name": "Namespace Devbox Agent",
      "description": "Managed agent running on a Namespace Devbox, with access to tools and resources on the Devbox.",
      "model": "claude-sonnet-4-6",
      "system": "You are a coding agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
      "mcp_servers": [],
      "tools": [
        {
          "type": "agent_toolset_20260401"
        }
      ],
      "skills": []
    }
    ```
  </Step>

  <Step title="Create a Session">
    <Info>
      Each Claude Agent session is backed by its own ephemeral Namespace Devbox. When you start a new session, Namespace provisions a fresh Devbox for it.
    </Info>

    To test the integration, start a new session with your agent.

    Head to your [workspaces sessions](https://platform.claude.com/workspaces/default/sessions), and create `New session`.
    Make sure to **select** the `Agent` and `Environment` you set up in the previous steps.

    Then give your agent an instruction like *"What OS are you running on?"*, and hit send.

    <GuideFlow id="0p058w5fvr" title="Interactive guide" frameSize="medium" />
  </Step>
</Steps>

## What's Next

Congratulations! You've successfully set up Claude Managed Agents with Devboxes. Your agents now have access
to high-performance, ephemeral execution environments backed by Namespace infrastructure.

From here, you can start putting your agents to work on real tasks: cloning repositories, running test suites,
debugging failing builds, or any other code-related workflows. Each new session spins up a fresh Devbox
automatically, so your agents always start from a clean state.

If you run into any issues or have questions along the way, don't hesitate to reach out to the
Namespace team. You can contact us at [support@namespace.so](mailto:support@namespace.so). We're happy
to help you get the most out of your setup.