> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing and access control

> Permission model and access control for ClickHouse Agents

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta feature. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Learn more.
                    </a>
                </u>
            </span>
        </div>;
};

ClickHouse Agents uses a layered permission model: roles control which features users can use at all, resource-level access lists control who can use a specific agent or other resource, and admin permissions control who manages everything.

<h2 id="roles">
  Roles
</h2>

A role is a bundle of feature permissions assigned to one or more users. The defaults:

* **User** - can run agents and chat. Whether they can build agents, create skills, share resources, etc. depends on the per-feature toggles in their role.
* **Admin** - everything in User, plus org-level controls: managing users, configuring the marketplace, granting permissions.

Admins can create custom roles with their own toggles for finer-grained control.

<h2 id="resource-sharing">
  Resource sharing
</h2>

Agents, prompts, and skills each have an access list. Three access levels per principal:

* **Viewer** - can use the resource but can't modify it.
* **Editor** - can change the resource's configuration (instructions, attached tools, model, etc.).
* **Owner** - Editor plus the ability to delete the resource or change its sharing.

When you create a resource, you're its owner by default. Anything you don't explicitly share is private to you.

<h2 id="principals">
  Principals
</h2>

You can grant access to:

* **Individual users** - one user at a time.
* **Groups** - teams or org units. If a user joins or leaves the group later, their access updates automatically.
* **Organization-wide** - everyone in the org sees the resource. Subject to the role-level toggle that allows this.

The org-wide visibility is what makes a resource discoverable in the [marketplace](/products/cloud/features/ai-ml/agents/marketplace).

<h2 id="share-an-agent">
  Share an agent
</h2>

Click the **share** icon at the bottom of the Agent Builder. A badge on the icon shows how many users or groups currently have access.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/XOOlYBuM8pBBOTzZ/images/cloud/agent-builder/sharing/sharing.webp?fit=max&auto=format&n=XOOlYBuM8pBBOTzZ&q=85&s=f46efe3ab7d11d0cfe7bfb5cacad492d" alt="Bottom of the Agent Builder panel with the share icon highlighted and a badge showing one shared principal" size="sm" width="696" height="1934" data-path="images/cloud/agent-builder/sharing/sharing.webp" />

The **Share** modal opens. Search for a user or group by name or email, choose the access level (**Viewer**, **Editor**, or **Owner**), and click **Save Changes**. To share organization-wide, enable the **Share with everyone in ClickHouse** toggle.

<Image img="https://mintcdn.com/private-7c7dfe99-detect-table-modification/XOOlYBuM8pBBOTzZ/images/cloud/agent-builder/sharing/share-agent-modal.webp?fit=max&auto=format&n=XOOlYBuM8pBBOTzZ&q=85&s=65818ba8c86d1b81fff9330b36473984" alt="Share modal with User and Group Permissions section, a search input, an existing user with an Owner role, a Share with everyone in ClickHouse toggle, and Cancel and Save Changes buttons" size="md" width="1544" height="824" data-path="images/cloud/agent-builder/sharing/share-agent-modal.webp" />

The recipient sees the agent in their available-agents list the next time they refresh. To revoke access, remove the row in the same modal. The recipient loses access immediately; their in-flight conversations finish but new ones won't open.

<h2 id="default-agent">
  Default agent
</h2>

You can mark one agent as your default. New conversations open against that agent unless you pick something else. Admins can also set an org-wide default for users who haven't picked their own.

<h2 id="admin-operations">
  Admin operations
</h2>

Admin-only operations include:

* Creating and editing roles.
* Configuring marketplace categories and curating featured agents.
* Enabling or disabling features at the org level (memory, web search, code interpreter, marketplace, etc.).
* Granting admin permissions to other users.

In ClickHouse Cloud, the admin panel is available to org admins. If you can't see it, contact your org admin or ClickHouse Cloud support to request access.

<h2 id="gotchas">
  Gotchas
</h2>

* **Deleting an agent breaks all sharing.** Recipients lose access; their saved conversations with the agent remain readable but can't be continued.
* **Editing a shared agent affects everyone using it.** Use a copy if you need to experiment without disrupting others.
* **Revoking a user's role doesn't delete the resources they created.** Their agents, prompts, and skills stay on their access lists; transfer ownership before fully off-boarding.