Blueprint Management

Preview: AI Builder Portal is in preview. Features may change as the product evolves.

Overview

A blueprint is a pre-configured workspace template. When a builder clicks “Create” in the AI Builder Portal, they are creating a private copy of a blueprint - pre-loaded with the right tools, the right database connections, and the right credentials for their role. They don’t configure anything. They just pick a template and start building. From a technical perspective, each blueprint maps to a Qovery project and environment. When a builder creates a workspace, the system clones that environment into a new Qovery project scoped to that builder. The blueprint is the master template; each workspace is an isolated copy. As an admin, you decide what each blueprint contains, who can access it, and what it can connect to. This is where governance happens - invisibly to the builder, but completely under your control. The blueprint itself is a standard Qovery environment, managed through the Qovery Console, CLI, or Terraform as usual.

Registering a Blueprint

Open the Admin Panel

Navigate to Admin > Blueprints in the AI Builder Portal.

Click Register

Click the Register Blueprint button to open the registration form.

Select the Qovery Project

Choose the Qovery project that contains your template environment. This project must already exist in your Qovery organization.

Choose the Environment

Select the specific environment within the project to use as the blueprint source. This is the environment that will be cloned when builders create workspaces.

If the selected project contains multiple environments, a dropdown appears to let you choose which environment to use as the blueprint source.

Set Display Name

Enter a display name that builders will see in the workspace catalog. Use a clear, descriptive name like “Full-Stack Starter” or “Python Data Science”.

Save

Click Register to add the blueprint. It will immediately appear in the catalog for users who have access.

Blueprint Requirements

A good blueprint environment should include everything a builder needs to be productive from the moment their workspace is ready. Required:

At least one service or container (typically a workspace image with an IDE like VS Code Server)

Recommended:

Development tools pre-installed - Claude Code, OpenCode, Git, language runtimes (Node.js, Python, etc.)
Environment variables configured - API keys, database credentials, service URLs
Databases and backing services - PostgreSQL, Redis, or any other services your builders need
TTL auto-stop job - A lifecycle job that automatically stops idle environments to save costs

Start with a lean blueprint that covers the basics. You can always iterate and add more tools or services based on builder feedback.

Updating a Blueprint

Changes you make to the source Qovery project and environment (adding services, updating environment variables, changing container images) are reflected in new workspaces created from the blueprint.

Existing workspaces are not automatically updated when the blueprint changes. Builders keep working on their current environment until an action is taken.

To apply updates to existing workspaces:

Image updates - Admins or builders can restart a workspace to pull the latest container image.
Structural changes - If the blueprint structure has changed significantly (new services added, environment variables renamed), you may need to use the Upgrade action from the workspace management page to redeploy with the latest blueprint configuration.

Removing a Blueprint

To unregister a blueprint, navigate to Admin > Blueprints, select the blueprint, and click Remove.

Removing a blueprint does not delete existing workspaces created from it. Those workspaces continue to run normally. However, no new workspaces can be created from the removed blueprint.

If you want to permanently clean up, delete the associated workspaces from the workspace management page before or after removing the blueprint.

Create Blueprint from Template

Instead of registering an existing Qovery environment as a blueprint, you can create a new blueprint directly from a pre-built template - no pre-existing environment required.

Open the Template Gallery

Navigate to Admin > Blueprints, click the dropdown arrow next to the Register Blueprint button, and select Create from Template.

Pick a Template

Browse the template gallery organized by persona category:

Developers

Full-stack, frontend, and backend starter templates.

Data

Data science and analytics templates.

Marketing

Campaign tools and content management templates.

Sales

CRM tools and pipeline reporting templates.

Finance

Financial analysis and reporting templates.

Other

General-purpose templates.

Select the template that best fits your use case.

Configure the Blueprint

Fill in the configuration form:

Blueprint name - Display name shown to builders in the catalog
Target cluster - The Kubernetes cluster where workspaces will run
Resource allocation - CPU, RAM, and storage limits for the workspace
Docker image repository - Container registry and image for the workspace
Project repository URL (optional) - Git repository to auto-clone into new workspaces

Create

Click Create. The portal provisions the Qovery project and environment automatically. The new blueprint appears in the catalog once provisioning is complete.

Use templates when you want a quick starting point without manually setting up Qovery projects and environments first. You can always customize the resulting blueprint environment in the Qovery Console after creation.

Blueprint Lifecycle

Each blueprint has an admin state that controls its visibility and availability in the catalog.

State	Catalog Visibility	Description
Testing	Shown with a “Coming Soon” badge	New blueprints start in this state. Admins can test them before making them available.
Enabled	Fully visible and launchable	Builders can create workspaces from this blueprint.
Disabled	Hidden from catalog	The blueprint is not available to builders. Existing workspaces are unaffected.

To change a blueprint’s state, open the blueprint detail page and use the state action buttons (Enable, Disable, Set Testing).

When a blueprint is in Testing state, it appears in the catalog with a “Coming Soon” badge. Only admins can launch test sessions from it - builders see the badge but cannot create workspaces.

Primary Service

By default, the portal connects terminal sessions and live preview to the first service in the blueprint environment. If your blueprint has multiple services, you can specify which service is the primary service - the one used for shell connections and preview. Navigate to Admin > Blueprints > [Blueprint] > General and select the primary service from the dropdown. The dropdown lists all services in the blueprint’s Qovery environment.

Set the primary service to the container running your IDE (e.g., code-server) so that terminal sessions and live preview connect to the right service automatically.

Workspace Project Mode

Choose how the portal organizes Qovery projects when builders create workspaces:

Mode	Behavior
Dedicated (default)	Each workspace gets its own Qovery project. Full isolation between workspaces.
Shared	All workspaces from this blueprint share a single Qovery project. Environments are created within the shared project. Uses fewer Qovery resources.

Configure this in Admin > Blueprints > [Blueprint] > General.

Use shared mode when you want to reduce the number of Qovery projects in your organization. Use dedicated mode (default) when workspace isolation is a priority.

Naming Templates

Customize how workspace projects and environments are named in Qovery using template variables:

Variable	Resolves to
`{user}`	The builder’s username (from email)
`{blueprint}`	The blueprint display name
`{random}`	A random alphanumeric string
`{name}`	The workspace name chosen by the builder

For example, a template of rde-{user}-{blueprint} for a user alice@company.com creating from “Frontend Starter” would produce rde-alice-frontend-starter.

Names are automatically sanitized to be Qovery-compatible (lowercase, alphanumeric, hyphens only).

Configure naming templates in Admin > Blueprints > [Blueprint] > General.

Target Cluster

If your organization has multiple Kubernetes clusters, you can specify which cluster should be used for workspaces created from a specific blueprint. Navigate to Admin > Blueprints > [Blueprint] > General and select the target cluster from the dropdown. If no cluster is specified, the portal uses the default cluster. This is useful for:

Data residency - Route workspaces to clusters in specific regions
Resource isolation - Separate development workloads across clusters
Specialized hardware - Use different node types or GPU-enabled clusters for specific blueprint use cases

Managing Blueprints with Terraform

Since blueprints are standard Qovery projects and environments, you can define and manage them entirely with the Qovery Terraform Provider. This lets you version-control your blueprint infrastructure, automate provisioning, and ensure consistency across environments.

Example: Blueprint with the Official Workspace Template

terraform {
  required_providers {
    qovery = {
      source  = "qovery/qovery"
    }
  }
}

provider "qovery" {
  token = var.qovery_api_token
}

data "qovery_organization" "my_org" {
  name = "My Organization"
}

data "qovery_cluster" "my_cluster" {
  organization_id = data.qovery_organization.my_org.id
  name            = "production"
}

# Create a project for the blueprint
resource "qovery_project" "blueprint" {
  organization_id = data.qovery_organization.my_org.id
  name            = "rde-blueprint-fullstack"
}

# Create the blueprint environment
resource "qovery_environment" "blueprint" {
  project_id = qovery_project.blueprint.id
  cluster_id = data.qovery_cluster.my_cluster.id
  name       = "blueprint"
  mode       = "DEVELOPMENT"
}

# Add the workspace container using the official template
resource "qovery_container" "workspace" {
  environment_id = qovery_environment.blueprint.id
  name           = "workspace"
  image_name     = "ghcr.io/qovery/remote-dev-env-template"
  tag            = "latest"
  cpu            = 2000
  memory         = 4096
  auto_deploy    = false

  ports = [
    {
      internal_port       = 8080
      external_port       = 443
      protocol            = "HTTP"
      publicly_accessible = true
      name                = "code-server"
    },
    {
      internal_port       = 9100
      external_port       = 443
      protocol            = "HTTP"
      publicly_accessible = true
      name                = "opencode"
    }
  ]

  environment_variables = [
    {
      key   = "GIT_REPO_URL"
      value = "https://github.com/your-org/your-starter-template"
    },
    {
      key   = "GIT_BRANCH"
      value = "main"
    },
    {
      key   = "DEV_PORT"
      value = "3100"
    }
  ]
}

Using Terraform is especially useful when managing multiple blueprints, enforcing consistent configuration across environments, or automating blueprint updates as part of a CI/CD pipeline.

Terraform Provider Overview

Get started with the Qovery Terraform Provider.

Provider Registry

Complete resource reference on the Terraform Registry.

Official Workspace Template

Qovery provides an official workspace template image you can use as the base container for your blueprints. It is designed for both technical and non-technical builders and comes pre-configured with everything needed for a productive development environment.

Source code and documentation: github.com/Qovery/remote-dev-env-template

What’s Included

code-server

VS Code running in the browser with a clean, builder-friendly UI. Dark theme, minimal distractions, Claude Code sidebar open by default.

AI Assistants

Claude Code (VS Code sidebar + CLI) and OpenCode (web chat UI) are pre-installed and pre-configured with builder-friendly AI skills.

Language Runtimes

Node.js 22, Python 3, Ruby + Bundler, and Go - ready to use out of the box for a wide range of project types.

Dev CLIs

GitHub CLI, Qovery CLI, and Git are pre-installed. Builders can push code, create PRs, and deploy without leaving the workspace.

Auto Dev Server

Automatically detects your project type and starts the right dev server - no manual configuration needed.

Live Preview

Built-in VS Code Live Preview extension for viewing your application directly in the editor.

Using the Template

To use this template as your blueprint’s workspace container:

Create a Qovery project and environment for your blueprint
Add a container service using the image from the template repository
Configure the environment variables listed below
Register the environment as a blueprint in the AI Builder Portal

Alternatively, fork the repository and build a custom image tailored to your organization’s needs, or use the install script to add RDE tools to your existing Dockerfile.

Using the Install Script

If you already have your own Dockerfile and base image, you can add all Qovery RDE tools with a single line instead of changing your base image or forking the template repository:

FROM your-org/your-base-image:latest

# Install all Qovery RDE tools (code-server, AI agents, runtimes, dev tools)
RUN curl -fsSL https://rde.qovery.com/install.sh | bash

WORKDIR /home/coder/project
EXPOSE 8080 9100
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

The script installs everything from the official template - code-server, Claude Code, OpenCode, Node.js, Python, Go, GitHub CLI, Zellij, and more - into any Debian or Ubuntu-based image.

The install script requires a Debian/Ubuntu-based image (it uses apt-get). It must run as root inside a RUN instruction.

Customizing with `.config.rde.qovery.yml`

To control which components are installed, place a .config.rde.qovery.yml file in your Docker build context. If no config file is present, everything is installed with sensible defaults. Each value can be:

true - install with default version
false - skip installation
A version string (e.g., "22", "1.24.3") - install with a specific version

# .config.rde.qovery.yml

# Workspace user (default: coder)
rde_user: "coder"

# Runtimes
nodejs: "22"        # Node.js 22 LTS
python: true        # latest Python 3
ruby: false         # skip Ruby
go: "1.24.3"        # Go 1.24.3

# AI Agents
claude_code: "2.1.129"
opencode: true
codex: false

# Developer Tools
gh: "2.74.1"
qovery_cli: true
zellij: true
ttyd: true
rtk: true           # token compression for AI tools

# Custom version checksums (required when overriding default versions)
# gh_sha256_amd64: "abc123..."
# gh_sha256_arm64: "def456..."
# go_sha256_amd64: "789abc..."
# go_sha256_arm64: "012def..."

# Code Server (VS Code in the browser)
code_server: "4.118.0"

# VS Code extensions (comma-separated)
extensions: anthropic.claude-code,github.copilot,ms-vscode.live-server

# Entrypoint and AI resources
entrypoint: true
qovery_skills: true

Reference it in your Dockerfile:

FROM ubuntu:24.04
COPY .config.rde.qovery.yml .
RUN curl -fsSL https://rde.qovery.com/install.sh | bash
WORKDIR /home/coder/project
EXPOSE 8080 9100
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

You can also set the config file path via the RDE_CONFIG environment variable:

RUN RDE_CONFIG=/path/to/custom-config.yml curl -fsSL https://rde.qovery.com/install.sh | bash

Available Components

Component	Config Key	Default Version	Description
Workspace user	`rde_user`	`coder`	Non-root user that owns the workspace
Node.js	`nodejs`	`22`	Node.js LTS via NodeSource
Python	`python`	system	Python 3 + pip + venv
Ruby	`ruby`	system	Ruby + Bundler
Go	`go`	`1.24.3`	Go language runtime
Claude Code	`claude_code`	`2.1.129`	AI coding assistant (VS Code + CLI)
OpenCode	`opencode`	latest	AI coding assistant (web UI)
Codex	`codex`	latest	OpenAI Codex CLI
GitHub CLI	`gh`	`2.74.1`	`gh` command-line tool
Qovery CLI	`qovery_cli`	latest	Qovery management CLI
Zellij	`zellij`	`0.44.3`	Terminal multiplexer for session persistence
ttyd	`ttyd`	`1.7.7`	Web-based terminal server
RTK	`rtk`	`0.42.0`	Token compression for LLM tools
code-server	`code_server`	`4.118.0`	VS Code in the browser
ripgrep	`ripgrep`	system	Fast recursive search
fzf	`fzf`	system	Fuzzy file finder

The install script and forking the template repository are complementary approaches. Use the install script when you want to keep your existing base image and add RDE tools on top. Fork the template when you want full control over the workspace image from scratch.

Integrity & Reproducibility

All binary downloads (Go, GitHub CLI, Zellij, ttyd, RTK) are SHA256-verified - the script checks each downloaded artifact against a pinned checksum and aborts the build if it doesn’t match. Node.js is installed via a GPG-verified apt source instead of piping a setup script into bash.

Using custom versions

When you override the default version of a binary tool, you must also provide SHA256 checksums for each architecture you target. The config key pattern is:

<tool>_sha256_<arch>

Where <tool> is one of go, gh, zellij, ttyd, or rtk, and <arch> is amd64 or arm64. For example, to pin GitHub CLI to v2.78.0 and Go to v1.25.0:

gh: "2.78.0"
gh_sha256_amd64: "a1b2c3d4e5f6..."
gh_sha256_arm64: "f6e5d4c3b2a1..."

go: "1.25.0"
go_sha256_amd64: "9a8b7c6d5e4f..."
go_sha256_arm64: "4f5e6d7c8b9a..."

You can find checksums on each tool’s GitHub releases page. For example, the GitHub CLI publishes a checksums.txt file with every release at https://github.com/cli/cli/releases.

If checksums are missing for a custom version, the install script will fail with an error to prevent installing unverified binaries.

Vendoring the install script

For production deployments where you need full control over what runs during your Docker build, vendor the install script into your repository instead of fetching it at build time:

# 1. Download the script once and commit it to your repo:
#    curl -fsSL https://rde.qovery.com/install.sh -o vendor/rde-install.sh

# 2. Use COPY instead of curl in your Dockerfile:
COPY .config.rde.qovery.yml /tmp/.config.rde.qovery.yml
COPY vendor/rde-install.sh /tmp/rde-install.sh
RUN RDE_CONFIG=/tmp/.config.rde.qovery.yml bash /tmp/rde-install.sh \
    && rm /tmp/rde-install.sh /tmp/.config.rde.qovery.yml

This eliminates the network fetch during build, pins the script to a known-good version in your git history, and lets you review changes before updating.

The Qovery CLI and Qovery Skills installs currently use unpinned curl | bash from Qovery-controlled endpoints (get.qovery.com and skill.qovery.com). Version pinning for these components is planned.

Custom workspace user

By default, the install script creates a coder user and installs everything under /home/coder. To use a different user, set rde_user in your config or the RDE_USER environment variable:

rde_user: "builder"

Or via environment variable (takes priority over config):

RUN RDE_USER=ubuntu curl -fsSL https://rde.qovery.com/install.sh | bash
WORKDIR /home/ubuntu/project

If the user already exists in your base image (e.g., node in node:22, ubuntu in ubuntu:24.04), the script will use it as-is and detect its home directory automatically. If it doesn’t exist, the script creates it with /home/<user>.

When using a custom user, update the WORKDIR in your Dockerfile to match the user’s home directory (e.g., /home/builder/project).

Environment Variables

Configure these environment variables on the workspace container service in your Qovery blueprint environment:

Variable	Required	Default	Description
`GIT_REPO_URL`	No	-	HTTPS URL of a Git repo to auto-clone into the workspace on startup
`GIT_TOKEN`	No	-	Personal access token for private repos. Auto-detects GitHub, GitLab, and Bitbucket.
`GIT_BRANCH`	No	`main`	Branch to checkout after cloning
`GIT_USER_NAME`	No	-	Git author name used for commits
`GIT_USER_EMAIL`	No	-	Git author email used for commits
`DEV_PORT`	No	`3100`	Port the auto-detected dev server listens on
`ANTHROPIC_API_KEY`	No	-	API key for Claude Code (if using API key auth mode in blueprint settings)
`DISABLE_CODE_SERVER`	No	-	Set to `true` to serve a welcome page instead of VS Code

For blueprints where builders will work on an existing codebase, set GIT_REPO_URL to your repository. For open-ended “start from scratch” blueprints, leave it empty - builders get a blank workspace with a welcome guide.

How the Startup Works

When a workspace container starts, the template automatically:

Clone the repository

If GIT_REPO_URL is configured, the repo is cloned and the specified branch is checked out. On subsequent restarts, the workspace pulls the latest changes instead of re-cloning.

Install dependencies

Auto-detects the project type and installs dependencies - npm install for Node.js, pip install for Python, bundle install for Ruby, go mod download for Go.

Start the dev server

Auto-detects the framework and starts the appropriate dev server in the background. Builders see their application running immediately.

Open the IDE

code-server launches with the Claude Code sidebar open and a welcome guide ready. For fresh workspaces (no git repo), a beginner-friendly WELCOME.md is generated with usage tips and example prompts.

Supported Project Types

The template auto-detects and handles the following project types:

Project Type	Detection	Dev Server
Vite (React, Vue, Svelte)	`vite` in package.json	`vite --port $DEV_PORT --host`
Next.js	`next` in package.json	`next dev -p $DEV_PORT`
Nuxt	`nuxt` in package.json	`nuxt dev --port $DEV_PORT`
Node.js (generic)	`package.json` with dev/start script	`npm run dev` or `npm start`
Django	`manage.py` present	`python3 manage.py runserver 0.0.0.0:$DEV_PORT`
Flask	`flask` in requirements.txt	`flask run --host=0.0.0.0 --port=$DEV_PORT`
FastAPI	`fastapi` in requirements.txt	`uvicorn main:app --host 0.0.0.0 --port $DEV_PORT`
Ruby on Rails	`rails` in Gemfile	`rails server -b 0.0.0.0 -p $DEV_PORT`
Go	`go.mod` present	`go run .`
Static HTML	`index.html` present	`npx serve -l $DEV_PORT`

AI Skills

The template includes pre-configured AI skills for both Claude Code and OpenCode that:

Adapt to the builder’s experience level - On first interaction, the AI asks the builder how comfortable they are with coding and adjusts its communication style accordingly (no jargon for beginners, normal technical language for experienced developers)
Take action directly - The AI creates files, installs packages, and fixes errors autonomously instead of instructing the builder to run commands
Use a sensible default stack - When starting from scratch, the AI defaults to Vite + React + Tailwind CSS
Support deployment - When a builder says “put it online” or “deploy”, the AI uses Qovery skills to deploy the application

Customization

Use the install script with your own Dockerfile

Add RUN curl -fsSL https://rde.qovery.com/install.sh | bash to your existing Dockerfile. Customize what gets installed with a .config.rde.qovery.yml file - disable runtimes you don’t need, pin specific versions, or skip code-server entirely. See Using the Install Script for details.

Fork and add your own tools

Fork the template repository, modify the Dockerfile to add your organization’s specific tools, libraries, or CLI utilities, then build and push your custom image to your container registry.

Customize AI behavior

The AI skill files (resources/CLAUDE.md and resources/SKILL.md) control how Claude Code and OpenCode interact with builders. Edit these files to match your organization’s coding conventions, preferred tech stack, or domain-specific instructions.

Add VS Code extensions

Add additional VS Code extensions to the Dockerfile using code-server --install-extension <extension-id>, or list them in the extensions key of your .config.rde.qovery.yml file. This is useful for language-specific extensions, linters, or your organization’s internal extensions.

Pre-configure for a specific stack

If all your builders use the same tech stack, set GIT_REPO_URL to a starter template repo and configure the environment variables accordingly. Builders get a ready-to-code project from the moment their workspace starts.

Best Practices

Keep blueprints lean and focused

Include only what builders actually need. A bloated blueprint means slower workspace creation, higher resource usage, and more maintenance. If different teams need different tools, create separate blueprints rather than one blueprint with everything.

Test blueprints before making them available

Deploy and validate the blueprint environment in the Qovery Console before registering it in the portal. Create a test workspace yourself to confirm that all services start correctly and the developer experience is smooth.

Use descriptive names for builders

Blueprint names appear in the workspace catalog. Use names that clearly communicate the purpose - “React Frontend Starter” is more helpful than “Template A”. Builders should be able to pick the right blueprint without asking for help.

Version your blueprint container images

Use tagged container images (e.g., workspace:v2.1) rather than :latest for production blueprints. This gives you control over when updates roll out and makes it easy to roll back if an update causes issues.

Configure auto-stop TTL policies

Include a TTL lifecycle job in your blueprint environment that automatically stops idle workspaces. This prevents forgotten workspaces from running indefinitely and accumulating cloud costs.

Next Steps

Access Control

Control who can create workspaces from each blueprint.

Workspace Management

Monitor and manage all workspaces across your organization.

Portal Customization

Customize branding, layouts, and the welcome screen.

​Overview

​Registering a Blueprint

​Blueprint Requirements

​Updating a Blueprint

​Removing a Blueprint

​Create Blueprint from Template

Developers

Data

Marketing

Sales

Finance

Other

​Blueprint Lifecycle

​Primary Service

​Workspace Project Mode

​Naming Templates

​Target Cluster

​Managing Blueprints with Terraform

​Example: Blueprint with the Official Workspace Template

Terraform Provider Overview

Provider Registry

​Official Workspace Template

​What’s Included

code-server

AI Assistants

Language Runtimes

Dev CLIs

Auto Dev Server

Live Preview

​Using the Template

​Using the Install Script

​Customizing with .config.rde.qovery.yml

​Available Components

​Integrity & Reproducibility

Using custom versions

Vendoring the install script

Custom workspace user

​Environment Variables

​How the Startup Works

​Supported Project Types

​AI Skills

​Customization

​Best Practices

​Next Steps

Access Control

Workspace Management

Portal Customization

Overview

Registering a Blueprint

Blueprint Requirements

Updating a Blueprint

Removing a Blueprint

Create Blueprint from Template

Blueprint Lifecycle

Primary Service

Workspace Project Mode

Naming Templates

Target Cluster

Managing Blueprints with Terraform

Example: Blueprint with the Official Workspace Template

Official Workspace Template

What’s Included

Using the Template

Using the Install Script

Customizing with `.config.rde.qovery.yml`

Available Components

Integrity & Reproducibility

Environment Variables

How the Startup Works

Supported Project Types

AI Skills

Customization

Best Practices

Next Steps