# Pi + Render: Deploy and manage your Render apps from Pi.

[Pi](https://pi.dev) is a minimal, self-extensible terminal coding agent. It ships no MCP support of its own, so Render's Pi package supplies both halves of the integration: Render's official skills for deploys, Blueprints, debugging, and monitoring, plus hosted Render MCP access through the `pi-mcp-adapter` extension. With both installed, Pi can inspect services, fetch logs, update environment variables, create supported services, and query Render Postgres from your shell.

## Setup contract

- Config file: `~/.pi/agent/settings.json`
- MCP install command: `pi install https://github.com/render-oss/render-pi-plugin`
- Skills command: `pi install https://github.com/render-oss/render-pi-plugin`
- Skills directory: `~/.pi/agent/git/github.com/render-oss/render-pi-plugin/skills/`
- Auth: OAuth
- Restart required: Yes
- Verify: `list_workspaces`

## Agent details

- Agent: Pi
- Docs: [Pi docs](https://pi.dev/docs/latest)
- Install: `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`
- Start: `pi`
- Skills mode: Agent-invoked

## Quick start

1. *Install Pi.*

   ```shell
   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
   ```

2. *Install the Render Pi package.* This installs Render's skills and the Render MCP configuration together:

   ```shell
   pi install https://github.com/render-oss/render-pi-plugin
   ```

   To pin the install to a specific release:

   ```shell
   pi install https://github.com/render-oss/render-pi-plugin@v0.1.0
   ```

   Pi installs the package's runtime dependencies, including its MCP adapter. There's no separate MCP package to install.

3. *Restart Pi* so it loads the new extension and skills.

4. *Connect to Render.* In a Pi session, run:

   ```text
   /mcp-auth render
   ```

   This opens the OAuth flow in your browser. For non-interactive environments, set `RENDER_API_KEY` instead. See the MCP configuration section below.

5. *Set your Render workspace* if you have multiple workspaces.

6. *Deploy a template.* Try a prompt like *"Deploy this project to Render and show me the plan before applying it."*

> On a clean first run, the adapter makes one best-effort connection to populate its tool-metadata cache before you have credentials, so Pi reports an HTTP 401 from the Render server once. This is expected. Pi and every Render skill still load normally, and the notice stops after you run `/mcp-auth render`.

## Quick links

- [Pi package](https://github.com/render-oss/render-pi-plugin)
- [Skills on GitHub](https://github.com/render-oss/skills)
- [MCP Server on GitHub](https://github.com/render-oss/render-mcp-server)
- [The Render CLI docs](/docs/cli)
- [Pi docs](https://pi.dev/docs/latest)

## MCP configuration

The Render Pi package configures the Render MCP server programmatically, so there's no MCP config file for you to edit. Pi records the package itself in `~/.pi/agent/settings.json` when you run `pi install`.

- MCP install command: `pi install https://github.com/render-oss/render-pi-plugin`
- MCP config file: `~/.pi/agent/settings.json`
- OAuth: Supported

#### OAuth (recommended)

Run this in a Pi session:

```text
/mcp-auth render
```

Your browser opens to sign in with your Render account, and credentials land in your operating system's credential store. No API key is needed. For details, see the [MCP server docs](/docs/mcp-server#1-connect-to-the-mcp-server).

#### API key

Set `RENDER_API_KEY` in the environment before starting Pi:

```shell
export RENDER_API_KEY=<YOUR_API_KEY>
```

The package reads the variable when it makes a lazy connection and sends it as a bearer token. Generate a key in your [account settings](https://dashboard.render.com/u/settings#api-keys). Use this method for non-interactive environments like CI/CD pipelines, and on headless Linux where OAuth needs an unlocked system credential store.

> Because the package owns its own MCP configuration, the Render server stays isolated from any MCP servers you set up yourself. The trade-off is that `/mcp setup`, `/mcp enable`, and `/mcp disable` don't apply to it, and `/mcp status` reports only what the package configured.

The prompts below can use a combination of MCP tools, Render skills, the Render CLI, and guided Dashboard or API steps.

## Example prompts

- *Deploy:* Deploy this project to Render.
- *Debug:* Check the deploy logs for the last failed deploy and fix the error.
- *Blueprint:* Create staging and production environments using a render.yaml Blueprint.
- *Database:* Create a Render Postgres database and wire DATABASE_URL to my web service.

## Render skills

Render's official *skills* give Pi task-specific procedures for deploys, debugging, monitoring, databases, Blueprints, and more. Pi keeps each skill's name and description in context, loads the full `SKILL.md` on demand, and registers every skill as a `/skill:render-*` command.

### Install skills

The [Render Pi package](https://github.com/render-oss/render-pi-plugin) is the preferred way to install skills, and it installs the Render MCP configuration at the same time:

```shell
pi install https://github.com/render-oss/render-pi-plugin
```

To get the skills without the MCP tools, run `pi config` and disable the package's extension while leaving its skills enabled.

Use the standalone skills installer if you don't want the package at all:

```shell
npx skills add render-oss/skills
```

### Skills catalog

- [render-background-workers](https://github.com/render-oss/skills/blob/main/skills/render-background-workers/SKILL.md): Sets up and configures background workers on Render for queue-based job processing.
- [render-blueprints](https://github.com/render-oss/skills/blob/main/skills/render-blueprints/SKILL.md): Authors and validates render.yaml Blueprints for Render infrastructure.
- [render-cli](https://github.com/render-oss/skills/blob/main/skills/render-cli/SKILL.md): Installs and uses the Render CLI for deploys, logs, SSH, psql, Blueprint validation, and automation.
- [render-cron-jobs](https://github.com/render-oss/skills/blob/main/skills/render-cron-jobs/SKILL.md): Configures and troubleshoots scheduled tasks on Render using cron job services.
- [render-debug](https://github.com/render-oss/skills/blob/main/skills/render-debug/SKILL.md): Debug failed Render deployments by analyzing logs, metrics, and database state.
- [render-deploy](https://github.com/render-oss/skills/blob/main/skills/render-deploy/SKILL.md): Deploy applications to Render by analyzing codebases, generating render.yaml Blueprints, and providing Dashboard deeplinks.
- [render-disks](https://github.com/render-oss/skills/blob/main/skills/render-disks/SKILL.md): Attaches and manages persistent disks on Render services—mount paths, sizing, snapshots, file transfers, and single-instance constraints.
- [render-docker](https://github.com/render-oss/skills/blob/main/skills/render-docker/SKILL.md): Builds and deploys Docker containers on Render—Dockerfiles, multi-stage builds, Blueprint Docker fields, private registries, layer caching, and platform constraints.
- [render-domains](https://github.com/render-oss/skills/blob/main/skills/render-domains/SKILL.md): Configures custom domains and TLS certificates on Render—DNS setup, CNAME records, apex domains, wildcard domains, and certificate troubleshooting.
- [render-env-vars](https://github.com/render-oss/skills/blob/main/skills/render-env-vars/SKILL.md): Configures environment variables, secrets, and env groups on Render.
- [render-keyvalue](https://github.com/render-oss/skills/blob/main/skills/render-keyvalue/SKILL.md): Provisions and configures Render Key Value (Redis-compatible Valkey 8) instances for caching, session storage, and job queues.
- [render-mcp](https://github.com/render-oss/skills/blob/main/skills/render-mcp/SKILL.md): Connects and configures the Render MCP server for AI coding tools—setup per tool (Cursor, Claude Code, Codex), authentication, workspace selection, tool catalog, and troubleshooting.
- [render-migrate-from-heroku](https://github.com/render-oss/skills/blob/main/skills/render-migrate-from-heroku/SKILL.md): Migrate from Heroku to Render by reading local project files and generating equivalent Render services.
- [render-monitor](https://github.com/render-oss/skills/blob/main/skills/render-monitor/SKILL.md): Monitor Render services in real-time.
- [render-networking](https://github.com/render-oss/skills/blob/main/skills/render-networking/SKILL.md): Connects Render services over the private network—internal DNS, service discovery, and cross-service communication.
- [render-postgres](https://github.com/render-oss/skills/blob/main/skills/render-postgres/SKILL.md): Sets up and optimizes Managed PostgreSQL on Render—connection strings (internal vs external), creation constraints, storage autoscaling, connection limits, high availability, read replicas, backups, and MCP inspection.
- [render-private-services](https://github.com/render-oss/skills/blob/main/skills/render-private-services/SKILL.md): Configures Render private services—internal-only apps that accept traffic exclusively from other Render services over the private network.
- [render-scaling](https://github.com/render-oss/skills/blob/main/skills/render-scaling/SKILL.md): Scales Render services—configures autoscaling targets, chooses instance types, sets manual instance counts, and optimizes cost.
- [render-static-sites](https://github.com/render-oss/skills/blob/main/skills/render-static-sites/SKILL.md): Deploys and configures static sites on Render's global CDN—build commands, publish paths, SPA routing, redirects, custom headers, and PR previews.
- [render-web-services](https://github.com/render-oss/skills/blob/main/skills/render-web-services/SKILL.md): Configures Render web services—port binding, TLS, health checks, custom domains, auto-deploy, PR previews, persistent disks, and deploy lifecycle.
- [render-workflows](https://github.com/render-oss/skills/blob/main/skills/render-workflows/SKILL.md): Sets up, develops, tests, and deploys Render Workflows.

## Common workflows

### Deploy from the terminal

1. Ask Pi to inspect the project and propose a Render deployment plan.
2. Review the generated Blueprint or service settings.
3. Let Pi apply supported changes with MCP or the Render CLI, or have it guide you through Dashboard or API steps.
4. Ask Pi to watch the first deploy.

### Debug a failing deployment

1. Ask Pi to fetch recent deploy logs.
2. Have it identify the most likely root cause.
3. Apply the code or env-var fix, then verify the next deploy.

### Add a database

1. Ask Pi to create a Render Postgres database.
2. Store the internal connection string as `DATABASE_URL`.
3. Run migrations from a pre-deploy command.

## Tips for success

- *Restart Pi after installing or updating the package.* Extensions and skills load at startup.
- *Invoke a skill directly with `/skill:render-deploy`* when you want a specific procedure instead of letting the model choose.
- *Keep Render config in the repository* so Pi can inspect infrastructure changes.
- *Ask for a plan before applying changes* when adding services, databases, or workers.

## FAQ

###### Why does Pi report a 401 from Render on first run?

The MCP adapter populates its tool-metadata cache with one best-effort connection on a clean first run, before you've authenticated. The 401 is that bootstrap, not a broken install. Pi and all of the Render skills load normally, and the notice stops once you run `/mcp-auth render` or set `RENDER_API_KEY`.

###### Does the Pi package have the same features as the other Render plugins?

Not yet. The Render packages for Claude Code, Cursor, Codex, and OpenCode also ship slash commands, a Render subagent, and a Blueprint validation hook. The Pi package is deliberately a subset: skills plus MCP access. Pi already exposes every skill as a `/skill:render-*` command, so the commands would be a second name for something you already have.

###### How do I update or remove the package?

Update every installed Pi package with `pi update --extensions`, or remove this one with `pi remove https://github.com/render-oss/render-pi-plugin`. An install pinned to a tag stays pinned; install a newer tag explicitly to move it forward.

## Troubleshooting

### The Render tools don't appear

Restart Pi. Extensions load at startup, so a `pi install` in another terminal has no effect on a running session. Then run `/mcp-auth render` and confirm `/mcp status` lists the `render` server.

### `/mcp setup`, `/mcp enable`, or `/mcp disable` don't affect Render

That's expected. The package supplies the Render server programmatically rather than through your MCP config file, which keeps it isolated from your own servers. Use `pi config` to disable the package's extension if you want to turn the Render tools off.

### OAuth fails on headless Linux

The OAuth flow writes credentials to the system credential store, which needs an unlocked keyring. Set `RENDER_API_KEY` before starting Pi instead.

## Community

*Render MCP Server*

Open-source MCP server source, install instructions, and tool reference.

*Render Skills*

The full skill catalog with `SKILL.md` files for every supported task.