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

# Agent Template

> The official Docker image template for running autonomous AI agents on Qovery - architecture, environment variables, customization, and governance.

<Warning>
  **Preview**: AI Builder Portal is in preview. Features and capabilities are under active development and may change.
</Warning>

## Overview

The [autonomous agent template](https://github.com/Qovery/autonomous-agent-template) is the official Docker image for running headless AI agents on Qovery. When deployed as a workspace, the container automatically reads the issue context (from Linear or Jira) injected by the portal, runs an AI agent, opens a pull request, and exits.

You can use the template directly or extend it with project-specific dependencies.

## Quick Start

### Use the image directly

```dockerfile theme={null}
FROM ghcr.io/qovery/autonomous-agent-template:latest

# Add your project-specific dependencies
RUN apt-get update && apt-get install -y your-deps
```

### Or build from source

```bash theme={null}
git clone https://github.com/Qovery/autonomous-agent-template.git
cd autonomous-agent-template
docker build -t my-autonomous-agent .
```

Then register the image as a blueprint in the portal and enable autonomous mode. See [Getting Started](/docs/rde/agents/getting-started) for the full walkthrough.

## How the Agent Run Works

When the portal launches a workspace from the template, the container executes a 7-step autonomous cycle:

<Steps>
  <Step title="Start governance proxy">
    If configured, the entrypoint starts an HTTP proxy that intercepts all outbound traffic from the agent and applies organization policies (allowlists, secret detection, rate limiting).
  </Step>

  <Step title="Read the issue context">
    The portal injects the issue key, title, and description as environment variables (tracker-agnostic). The script writes them to a task file. The container talks only to the portal - no tracker token or tracker-specific identifiers are injected.
  </Step>

  <Step title="Clone the repository and create a branch">
    The target repository is cloned using the configured git token. A branch is created automatically from the issue key and title (e.g., `agent/ENG-123-fix-login-validation`).
  </Step>

  <Step title="Run the AI agent">
    The configured runtime executes headlessly with the task file as the prompt:

    | Runtime     | Command                      |
    | ----------- | ---------------------------- |
    | Claude Code | `claude -p "<task>"`         |
    | OpenCode    | `opencode run "<task>"`      |
    | Codex       | `codex --full-auto "<task>"` |
    | Gemini CLI  | `gemini -p "<task>"`         |
    | Cursor CLI  | `cursor-agent "<task>"`      |

    The command is wrapped in a `timeout` using the configured run timeout. Exit code 124 indicates a timeout.

    During execution, the agent can stream live progress updates via the portal's progress endpoint (`RDE_RUN_PROGRESS_URL`). The portal relays them to the tracker - as real-time "thought" activities in Linear, or as progress comments in Jira.
  </Step>

  <Step title="Commit and push">
    If the agent made code changes, they are committed and pushed to the branch. If no changes were made, the run reports a failure ("no code changes").
  </Step>

  <Step title="Open a pull request">
    A PR is created on the git provider (GitHub, GitLab, or Bitbucket) with the issue context in the body. The PR title includes the issue key.
  </Step>

  <Step title="Report results">
    The container calls back to the portal API (`RDE_RUN_CALLBACK_URL`) to record the result. The portal then reports back on the tracker - in Linear, updating the agent plan, adding external URLs (dashboard link, PR link), and posting a response or error activity inline; in Jira, posting a comment and transitioning the issue status. A lifecycle comment is posted for audit purposes. The workspace is automatically cleaned up after completion.
  </Step>
</Steps>

## Environment Variables

These variables are injected automatically by the portal when it launches the workspace. You do not set them manually.

The issue context is injected in a tracker-agnostic form. The container never receives a tracker token or tracker-specific identifiers - it reports back to the portal, which talks to Linear or Jira on its behalf.

| Variable                   | Description                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `RDE_AUTONOMOUS`           | Set to `1` when running in autonomous mode                           |
| `RDE_AUTONOMOUS_PROVIDER`  | Issue tracker for this run: `linear` or `jira`                       |
| `RDE_AUTONOMOUS_AGENT`     | Runtime to use: `claude`, `opencode`, `codex`, `gemini`, or `cursor` |
| `RDE_ISSUE_KEY`            | Human-readable issue key (e.g., `ENG-123`)                           |
| `RDE_ISSUE_TITLE`          | Issue title                                                          |
| `RDE_ISSUE_DESCRIPTION`    | Issue description                                                    |
| `RDE_AGENT_SYSTEM_PROMPT`  | Optional system prompt from the blueprint                            |
| `RDE_RUN_ID`               | Unique run identifier                                                |
| `RDE_RUN_CALLBACK_URL`     | Portal API callback URL for reporting the final result               |
| `RDE_RUN_PROGRESS_URL`     | Portal endpoint for streaming live progress updates                  |
| `RDE_RUN_MESSAGES_URL`     | Portal endpoint for polling follow-up instructions                   |
| `RDE_RUN_TIMEOUT_MIN`      | Hard timeout for the agent run (minutes)                             |
| `ANTHROPIC_API_KEY`        | API key for Claude Code, OpenCode, or Cursor runtimes                |
| `OPENAI_API_KEY`           | API key for Codex runtime                                            |
| `GEMINI_API_KEY`           | API key for Gemini CLI runtime                                       |
| `BLUEPRINT_GIT_REPOSITORY` | Target repository URL (inherited from the blueprint environment)     |
| `BLUEPRINT_GIT_TOKEN`      | Git token for clone, push, and PR creation                           |
| `BLUEPRINT_GIT_PROVIDER`   | Git provider: `github`, `gitlab`, or `bitbucket`                     |

The portal also injects Qovery deploy credentials (`QOVERY_CLI_ACCESS_TOKEN`, `QOVERY_ORGANIZATION_ID`, `QOVERY_CLUSTER_ID`, `QOVERY_PROJECT_ID`) so the agent can run preview deployments.

## Git Provider Support

The template supports three git providers for cloning repositories, pushing branches, and creating pull requests:

| Provider  | Value       | PR API             |
| --------- | ----------- | ------------------ |
| GitHub    | `github`    | GitHub REST API    |
| GitLab    | `gitlab`    | GitLab REST API    |
| Bitbucket | `bitbucket` | Bitbucket REST API |

The provider is determined by the `BLUEPRINT_GIT_PROVIDER` environment variable, which is set automatically based on the repository URL configured in the agent blueprint.

## RDE Configuration

The template includes a `.config.rde.qovery.yml` file that customizes which components are installed by the Qovery RDE install script. It disables web IDE components that are not needed for headless autonomous mode while keeping all AI runtimes and development tooling.

**Enabled components:**

* All AI runtimes (Claude Code, OpenCode, Codex, Cursor)
* Development tools (Node.js, Python, Ruby, Go)
* Git tooling (gh CLI, Qovery CLI)
* Terminal utilities (zellij, fzf, ripgrep)

**Disabled components:**

* Code Server (web IDE) - not needed for headless mode
* Standard entrypoint - replaced by the autonomous entrypoint
* Browser-based extensions and resources

See [Blueprint Management](/docs/rde/admin/blueprint-management#official-workspace-template) for details on the RDE install script and `.config.rde.qovery.yml` configuration.

## Agent Governance Proxy

When the `RDE_PROXY_SCRIPT_GZ_B64` environment variable is set, the template starts an HTTP proxy before running the agent. This proxy intercepts all outbound HTTP/HTTPS traffic from the AI agent and enforces organization policies.

The proxy supports:

* **Allowlists** - restrict which external hosts the agent can reach
* **Secret detection** - prevent accidental exfiltration of credentials
* **Rate limiting** - throttle API calls to prevent abuse
* **Kill switch** - immediately halt all agent egress

The proxy runs on port 8877 and is transparent to the agent. All outbound traffic is routed through it automatically.

<Info>
  The governance proxy is configured at the organization level by the Qovery team. Contact Qovery support to enable and configure proxy policies for your autonomous agents.
</Info>

## Customizing the Template

To extend the template for your project:

```dockerfile theme={null}
FROM ghcr.io/qovery/autonomous-agent-template:latest

# Add project-specific dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools

# Add custom agent instructions
COPY AGENTS.md /home/coder/project/AGENTS.md

# Add custom scripts
COPY my-setup.sh /usr/local/bin/my-setup.sh
RUN chmod +x /usr/local/bin/my-setup.sh
```

Common customizations:

* **Project dependencies** - install language-specific packages or system libraries your codebase requires
* **Agent instructions** - add an `AGENTS.md` or `.claude/` directory with project-specific context for the AI agent
* **Setup scripts** - run initialization steps before the agent starts (e.g., database migrations, seed data)
* **Additional tools** - install linters, formatters, or test frameworks the agent needs

<Tip>
  Keep the base image as your `FROM` layer and add customizations on top. This ensures you get updates to the AI runtimes, governance proxy, and core scripts automatically when the base image is updated.
</Tip>

## Next Steps

<CardGroup cols={3}>
  <Card title="Getting Started" icon="play" href="/docs/rde/agents/getting-started">
    Set up your first autonomous agent from scratch.
  </Card>

  <Card title="Agent Blueprints" icon="cubes" href="/docs/rde/agents/agent-blueprints">
    Configure runtime, repositories, and tracker integration.
  </Card>

  <Card title="Jira Integration" icon="arrows-rotate" href="/docs/rde/agents/jira-integration">
    Connect Jira, map statuses, and trigger agents by assignment.
  </Card>
</CardGroup>