Agent Template

Preview: AI Builder Portal is in preview. Features and capabilities are under active development and may change.

Overview

The 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

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

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 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:

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

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.

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

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.

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”).

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.

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.

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

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.

Customizing the Template

To extend the template for your project:

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

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.

Next Steps

Getting Started

Set up your first autonomous agent from scratch.

Agent Blueprints

Configure runtime, repositories, and tracker integration.

Jira Integration

Connect Jira, map statuses, and trigger agents by assignment.

​Overview

​Quick Start

​Use the image directly

​Or build from source

​How the Agent Run Works

​Environment Variables

​Git Provider Support

​RDE Configuration

​Agent Governance Proxy

​Customizing the Template

​Next Steps

Getting Started

Agent Blueprints

Jira Integration

Overview

Quick Start

Use the image directly

Or build from source

How the Agent Run Works

Environment Variables

Git Provider Support

RDE Configuration

Agent Governance Proxy

Customizing the Template

Next Steps