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

# Let a Coding Agent Deploy Without Cloud Admin Credentials

> Give Claude Code, Codex, Cursor, or another coding agent the ability to deploy, check logs, and create preview environments on your own AWS, GCP, Azure, or Kubernetes, with a scoped token instead of cloud admin access.

Use Qovery when you want a coding agent to deploy and operate apps on your own cloud account or Kubernetes cluster, but you do not want to hand it cloud admin credentials. Your cloud account is connected to Qovery once, by a human. The agent only receives a Qovery token, and that token can be limited to exactly what the agent needs, for example "deploy the staging environment, never delete anything".

## What the agent gets

| Need | What to give the agent |
| - | - |
| Deploy apps, create preview environments, scale, roll back | [Qovery Agent Skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md) and the [Qovery CLI](https://www.qovery.com/docs/cli/overview.md) |
| Read status and logs, investigate failures | The [Qovery MCP Server](https://www.qovery.com/docs/copilot/mcp-server.md) (read-only by default) |
| A credential with limited permissions | An [API Policy Token](https://www.qovery.com/docs/configuration/organization/api-policy-token.md) (Preview) that allows the writes the agent needs. An API token with a read-only role is enough for investigation only. |

The agent never needs AWS, GCP, or Azure credentials.

## Prerequisites

> [!TIP]
>
> A Qovery organization with a cluster on your cloud account. To create one, see [Install Qovery on your cloud](https://www.qovery.com/docs/getting-started/quickstart/cloud.md). The agent can also create the account itself with the `qovery-signup` skill, which authenticates with `qovery auth --headless` (the first login creates the account).

> [!TIP]
>
> An organization **Owner** or **Admin** to create the API Policy Token. Custom roles cannot create one.

> [!TIP]
>
> A coding agent that supports [Agent Skills](https://agentskills.io): Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and others. See [Compatible tools](https://www.qovery.com/docs/getting-started/quickstart/ai-agent.md#compatible-tools).

## Steps

**1. Install the Qovery Agent Skills and CLI**

```bash theme={null}
# Agent Skills, available to every project on this machine
curl -fsSL https://skill.qovery.com/install.sh | bash

# Qovery CLI (Linux and macOS; see the CLI page for other methods)
curl -s https://get.qovery.com | bash
```

To install the skills for the current repository only, run `curl -fsSL https://skill.qovery.com/install.sh | bash -s -- --project`.

**2. Create a scoped token for the agent**

> [tab] With the coding agent
>
> In a session authenticated as an organization Owner or Admin (`qovery auth`, or `qovery auth --headless` without a browser), ask the agent:
>
> ```
> /qovery-policy-token read-only on staging, can deploy the api service
> ```
>
> The `qovery-policy-token` skill turns this intent into an OPA/Rego policy, tests it locally and against the API, creates the token, and checks that it allows what you asked and denies everything else.

> [tab] In the Console
>
> 1. Open your organization settings, then the **Token API** section.
> 2. In **Policy API Token**, click **Add new**.
> 3. Enter a name, a description, and the policy. The form is prefilled with a [starter policy](https://www.qovery.com/docs/configuration/organization/api-policy-token.md#starter-policy) that grants read access to one environment, write access to one service without deletion, and deployment of that environment.
> 4. Copy the token (`sk-qov-01-...`). It is displayed once.

> [!WARNING]
>
> An API Policy Token authenticates as organization admin, and its policy is the only constraint: a policy that allows everything grants everything. Only allow the requests the agent needs. API Policy Tokens are in Preview; see [Current limitations](https://www.qovery.com/docs/configuration/organization/api-policy-token.md#current-limitations).

**3. Give the token to the agent session**

Set the token in the environment of the agent session. Do not paste it into the prompt.

```bash theme={null}
export QOVERY_CLI_ACCESS_TOKEN="sk-qov-01-..."
```

The Qovery CLI, which the skills drive, reads `QOVERY_CLI_ACCESS_TOKEN` and sends it as `Authorization: Token ...`. The policy also applies to the lookups the CLI makes to resolve organization, project, and environment names, so the policy must allow those reads.

For read-only investigation from the same session, you can also add the [MCP Server](https://www.qovery.com/docs/copilot/mcp-server.md). It does not use the API Policy Token: give it an API token with a read-only role in the `Authorization` header. If you sign in to the MCP Server with OAuth instead, it acts with your own user permissions.

```bash theme={null}
claude mcp add --transport http qovery https://mcp.qovery.com/mcp --header "Authorization: Token $QOVERY_READONLY_TOKEN"
```

**4. Restrict the commands the agent can run (optional)**

The token is the guardrail that Qovery enforces. You can also restrict which `qovery` commands the agent runs without asking, with a permission file committed to the repository. See the Claude Code allowlist in [Securing AI Agent Access](https://www.qovery.com/docs/copilot/securing-ai-access.md#option-2-cli-permission-allowlist).

**5. Ask the agent to deploy**

```
Deploy my application with Qovery
```

```
Create a preview environment for the current branch
```

```
My Qovery deployment is failing, can you help?
```

The agent picks `qovery-deploy`, `qovery-preview`, or `qovery-troubleshoot` from the prompt.

## Check the result

* The deployment reaches the `DEPLOYED` state. With the CLI, `--watch` exits with code `0` on success and `1` on failure:

  ```bash theme={null}
  qovery environment deploy --environment "staging" --watch
  ```

* A request outside the policy is refused with `401 Unauthorized`. A denied request does not tell you which rule failed, so test the policy before you rely on it (the `qovery-policy-token` skill does this for you).

* Changes the agent makes appear in the [audit logs](https://www.qovery.com/docs/getting-started/security-and-compliance/audit-logs.md) under the token name.

## Related

> [card] [Qovery Agent Skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md)
>
> All eleven skills and the prompts that trigger them.

> [card] [API Policy Token (Preview)](https://www.qovery.com/docs/configuration/organization/api-policy-token.md)
>
> Policy input contract, recipes, and limitations.

> [card] [Securing AI Agent Access](https://www.qovery.com/docs/copilot/securing-ai-access.md)
>
> Read-only MCP, CLI allowlist, and policy tokens compared.

> [card] [Preview Environments](https://www.qovery.com/docs/getting-started/guides/use-cases/preview-environments.md)
>
> One environment per pull request, deleted when the PR closes.


## Related topics

- [Deploy Your First Application](https://www.qovery.com/docs/getting-started/guides/getting-started/deploy-your-first-application.md)
- [Deploy with AI Agent](https://www.qovery.com/docs/getting-started/quickstart/ai-agent.md)
- [Cloud Credentials](https://www.qovery.com/docs/configuration/organization/cloud-credentials.md)
- [Deploy from a Repository with the CLI and API](https://www.qovery.com/docs/getting-started/quickstart/cli-and-api.md)
- [Bring Your Own Kubernetes (BYOK)](https://www.qovery.com/docs/configuration/integrations/kubernetes/byok.md)


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