Aiven Runtime for agents: deploy an app or agent, service integrations, example prompts

TL;DR: This page is written for a coding agent that needs to deploy something to Aiven Runtime at task time. It covers the deploy flow, how service integrations deliver connection URIs, example prompts for Claude Code, Cursor, Codex and Gemini CLI, and a troubleshooting table. Unverified details are marked.

Facts an agent needs

• Runtime builds applications from a Containerfile, a Dockerfile or a Compose file.
• Data services such as Aiven for PostgreSQL are managed Aiven services, connected through integrations. They are not containers you run yourself.
• On integration, Aiven injects one connection URI environment variable per integrated service. The exact variable names depend on the service; read them from the Console or from a printed list of env var names, never guess [TO VERIFY].
• The Aiven MCP server provisions and manages services and offers bounded read-only SQL. It does not give an application a data path.

flowchart LR
  R["Repo with Containerfile"] --> B["Runtime build"]
  B --> S["Application service"]
  S --- I["Integration"]
  I --- D["Aiven for PostgreSQL"]
  I -->|"injects connection URI"| S

Deploy an app: checklist

1. Make sure the repository has a Containerfile or Dockerfile that builds on a clean machine.
2. Make the app listen on 0.0.0.0 and a single port; document the port [TO VERIFY: port convention on Runtime].
3. Read all configuration from environment variables.
4. Add a health endpoint that touches the database.
5. Deploy through the Console or the supported CLI path [TO VERIFY].
6. Add the integration to each data service.
7. Smoke test from outside.

Expected after step 6: the service restarts and the integration shows as active.

Turning one URI into discrete values

Some clients want separate host, port and password values. Parse the injected URI rather than asking for four secrets:

import os
from urllib.parse import urlparse

u = urlparse(os.environ["DATABASE_URL"])
cfg = {
    "host": u.hostname,
    "port": u.port,
    "user": u.username,
    "password": u.password,
    "dbname": u.path.lstrip("/"),
}

Use sslmode=verify-full and the project CA when the client allows it.

Handling TLS correctly

Aiven data services require TLS. A handshake error means the client does not trust the server certificate or is not speaking TLS. The fix is to supply the project CA, not to set verification to off. A silenced check removes the one control that tells you whether you are talking to your own database.

# example compose-style environment (placeholders only)
services:
  web:
    build: .
    environment:
      PGSSLMODE: verify-full
      PGSSLROOTCERT: /app/ca.pem

Whether Runtime reads the environment block from Compose as written here depends on how it classifies the file [TO VERIFY]. DATABASE_URL itself comes from the integration, not from this file.

Example prompts

For a longer walk-through see Deploy a PostgreSQL-backed app to Runtime, and for an agent with memory see deploy an AI agent next to its data.

Limits of this page

It covers the shape of the workflow, not exact flags. Where a command, plan limit or variable name appears with a marker, confirm it in the official docs first. Runtime pricing and plan limits are intentionally absent.

When this goes wrong

What to verify before you rely on this

• Every [TO VERIFY] marker is resolved against the Aiven docs.
• The agent was told not to provision without approval.
• No secrets appear in prompts, logs or commits.