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

# Self-hosted agents overview

> Create and manage self-hosted agent pools, authentication secrets, and project assignments in env zero for Kubernetes and Docker agents.

## What Are Self-Hosted Agents

Self-hosted agents run env zero deployment workloads on your own infrastructure.

* Execution is contained within your own servers and infrastructure.
* The agent requires an internet connection but no inbound network access.
* Secrets are stored on your own infrastructure.

> [!NOTE]
>
> Self-hosted agents are available to Enterprise customers only. See [pricing](https://www.envzero.com/pricing) for details.

env zero supports two agent types:

* **Kubernetes agent** - Runs on your Kubernetes cluster using a Helm chart. See [Kubernetes Agent Installation](https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/self-hosted-kubernetes-agent.md).
* **Docker agent** - Runs as a standalone Docker container. See [Docker Agent Installation](https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/standalone-docker-agent.md).

## Agent Pools

An agent pool is a logical grouping of one or more agent instances that share the same configuration and authentication. You can create and manage agent pools in the env zero UI.

Each agent pool has:

* A unique name within your organization
* Up to two authentication secrets
* Optional log hosting configuration

![Agent Pools page showing agent list with status, version, and actions](https://mintcdn.com/envzero-b61043c8/G6uQW-C5k8CwAvji/images/guides/admin-guide/self-hosted-kubernetes-agent/agents-list-page.png?fit=max\&auto=format\&n=G6uQW-C5k8CwAvji\&q=85\&s=156e622a7ace5eeb7e2d0eb78b4b54fe)

## Permissions

Managing agent pools requires the **Edit Organization Settings** permission.

This permission is required to:

* Create, edit, and delete agent pools
* Create and revoke agent secrets
* Assign agents to projects

## Creating an Agent Pool

**1. Navigate to Agents**

Go to **Organization Settings** > **Agents**.

**2. Create the agent pool**

Click **Create Agent**. Enter a name for the agent pool (required, must be unique within your organization).

**3. Create an authentication secret**

After creating the agent pool, the secrets modal opens automatically. Click **Create Secret** to generate an authentication token. See [Managing Agent Secrets](#managing-agent-secrets) for details.

![Create Agent modal showing name input field](https://mintcdn.com/envzero-b61043c8/G6uQW-C5k8CwAvji/images/guides/admin-guide/self-hosted-kubernetes-agent/create-agent-modal.png?fit=max\&auto=format\&n=G6uQW-C5k8CwAvji\&q=85\&s=315653734d8002c21a27cc01cc2d25dc)

## Managing Agent Secrets

Agent secrets are authentication tokens used to connect agent instances to env zero. Each agent pool supports up to two secrets, allowing you to rotate credentials without downtime.

### Creating a Secret

**1. Open the secrets modal**

From the Agents list, click **Manage Secrets** on the agent pool.

**2. Generate the secret**

Click **Create Secret** and enter a name. The secret value is displayed once. Copy it immediately.

**3. Use the secret to install your agent**

The modal displays ready-to-use install commands:

**Helm (Kubernetes):**

```shell theme={null}
helm install --create-namespace env0-agent env0/env0-agent --namespace env0-agent --set-string agentAccessToken='<your-agent-access-token>'
```

**Docker:**

```shell theme={null}
docker run -e AGENT_ACCESS_TOKEN='<your-agent-access-token>' ghcr.io/env0/deployment-agent:latest
```

> [!WARNING]
>
> The secret value is shown only once at creation time. If you lose it, revoke the secret and create a new one.

![Create Secret modal showing the generated token and install commands](https://mintcdn.com/envzero-b61043c8/G6uQW-C5k8CwAvji/images/guides/admin-guide/self-hosted-kubernetes-agent/create-secret-modal.png?fit=max\&auto=format\&n=G6uQW-C5k8CwAvji\&q=85\&s=473b55913851703a9d901d62d99ad5ee)

### Revoking a Secret

To revoke a secret, open the secrets modal and click **Revoke** next to the secret. Revocation is immediate and irreversible.

> [!WARNING]
>
> Revoked secrets may remain valid for up to 60 minutes due to authentication caching. Plan secret rotations accordingly.

## Editing an Agent Pool

To edit an agent pool, click **Edit** on the agent row in the Agents list. You can modify:

* **Name** - The display name of the agent pool.
* **Log configuration** - You can switch between env zero hosted and self-hosted deployment log storage. See [Hosting deployment logs](https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/hosting-the-deployment-logs.md) for details.

![Edit Agent Configuration modal showing name and deployment logs settings](https://mintcdn.com/envzero-b61043c8/G6uQW-C5k8CwAvji/images/guides/admin-guide/self-hosted-kubernetes-agent/edit-agent-modal.png?fit=max\&auto=format\&n=G6uQW-C5k8CwAvji\&q=85\&s=3b37d1b96126baffb28c441dad48bc1f)

## Deleting an Agent Pool

To delete an agent pool, click **Delete** on the agent row. You must type the agent name to confirm deletion.

> [!WARNING]
>
> You cannot delete an agent pool that is set as the organization default or is assigned to any projects. Reassign or remove the agent from all projects before deleting.

## Assigning Agents to Projects

You can assign specific agent pools to individual projects. Projects not assigned to a specific agent use the organization's default agent.

To assign agents to projects, go to **Organization Settings** > **Agents**. The agent assignment table shows each project and its assigned agent. Select an agent pool from the dropdown to change the assignment.

![Agent assignment table showing projects and their assigned agents](https://mintcdn.com/envzero-b61043c8/G6uQW-C5k8CwAvji/images/guides/admin-guide/self-hosted-kubernetes-agent/agent-assignment-table.png?fit=max\&auto=format\&n=G6uQW-C5k8CwAvji\&q=85\&s=fe2f24fe2ef81cf0a1a6e50df12a134b)

For more information about running multiple agents, including hybrid setups with both self-hosted and SaaS agents, see [Running multiple self-hosted agents](https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/multiple-self-hosted-agents.md).

## Next steps

* [Tune the Kubernetes agent's Helm values](https://docs.envzero.com/guides/admin-guide/self-hosted-kubernetes-agent/custom-optional-configuration.md)
* [Connect your Git repository](https://docs.envzero.com/guides/admin-guide/manage-vcs.md) so the agent can deploy from it


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.