> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Render

Deploy Agdi on Render using Infrastructure as Code. The included `render.yaml` Blueprint defines your entire stack declaratively, service, disk, environment variables, so you can deploy with a single click and version your infrastructure alongside your code.

## Prerequisites

* A [Render account](https://render.com) (free tier available)
* An API key from your preferred [model provider](https://agdiai-597e782f.mintlify.site/providers.md)

## Deploy with a Render Blueprint

[Deploy to Render](https://render.com/deploy?repo=https://github.com/agdi/agdi)

Clicking this link will:

1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
2. Build the Docker image and deploy

Once deployed, your service URL follows the pattern `https://<service-name>.onrender.com`.

## Understanding the Blueprint

Render Blueprints are YAML files that define your infrastructure. The `render.yaml` in this
repository configures everything needed to run Agdi:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
services:
  - type: web
    name: agdi
    runtime: docker
    plan: starter
    healthCheckPath: /health
    envVars:
      - key: OPENCLAW_GATEWAY_PORT
        value: "8080"
      - key: OPENCLAW_STATE_DIR
        value: /data/.agdi
      - key: OPENCLAW_WORKSPACE_DIR
        value: /data/workspace
      - key: OPENCLAW_GATEWAY_TOKEN
        generateValue: true # auto-generates a secure token
    disk:
      name: agdi-data
      mountPath: /data
      sizeGB: 1
```

Key Blueprint features used:

| Feature | Purpose |
| - | - |
| `runtime: docker` | Builds from the repo's Dockerfile |
| `healthCheckPath` | Render monitors `/health` and restarts unhealthy instances |
| `generateValue: true` | Auto-generates a cryptographically secure value |
| `disk` | Persistent storage that survives redeploys |

## Choosing a plan

| Plan | Spin-down | Disk | Best for |
| - | - | - | - |
| Free | After 15 min idle | Not available | Testing, demos |
| Starter | Never | 1GB+ | Personal use, small teams |
| Standard+ | Never | 1GB+ | Production, multiple channels |

The Blueprint defaults to `starter`. To use free tier, change `plan: free` in your fork's
`render.yaml` (but note: no persistent disk means config resets on each deploy).

## After deployment

### Access the Control UI

The web dashboard is available at `https://<your-service>.onrender.com/`.

Connect using the `OPENCLAW_GATEWAY_TOKEN` value that was auto-generated during deploy (find it in **Dashboard → your service → Environment**).

## Render Dashboard features

### Logs

View real-time logs in **Dashboard → your service → Logs**. Filter by:

* Build logs (Docker image creation)
* Deploy logs (service startup)
* Runtime logs (application output)

### Shell access

For debugging, open a shell session via **Dashboard → your service → Shell**. The persistent disk is mounted at `/data`.

### Environment variables

Modify variables in **Dashboard → your service → Environment**. Changes trigger an automatic redeploy.

### Auto-deploy

If you use the original Agdi repository, Render will not auto-deploy your Agdi. To update it, run a manual Blueprint sync from the dashboard.

## Custom domain

1. Go to **Dashboard → your service → Settings → Custom Domains**
2. Add your domain
3. Configure DNS as instructed (CNAME to `*.onrender.com`)
4. Render provisions a TLS certificate automatically

## Scaling

Render supports horizontal and vertical scaling:

* **Vertical**: Change the plan to get more CPU/RAM
* **Horizontal**: Increase instance count (Standard plan and above)

For Agdi, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.

## Backups and migration

Export your configuration and workspace at any time using the shell access in the Render Dashboard:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi backup create
```

This creates a portable backup archive you can restore on any Agdi host. See [Backup](https://agdiai-597e782f.mintlify.site/cli/backup.md) for details.

## Troubleshooting

### Service will not start

Check the deploy logs in the Render Dashboard. Common issues:

* Missing `OPENCLAW_GATEWAY_TOKEN` — verify it is set in **Dashboard → Environment**
* Port mismatch — ensure `OPENCLAW_GATEWAY_PORT=8080` is set so the gateway binds to the port Render expects

### Slow cold starts (free tier)

Free tier services spin down after 15 minutes of inactivity. The first request after spin-down takes a few seconds while the container starts. Upgrade to Starter plan for always-on.

### Data loss after redeploy

This happens on free tier (no persistent disk). Upgrade to a paid plan, or
regularly export your config via `agdi backup create` in the Render shell.

### Health check failures

Render expects a 200 response from `/health` within 30 seconds. If builds succeed but deploys fail, the service may be taking too long to start. Check:

* Build logs for errors
* Whether the container runs locally with `docker build && docker run`

## Next steps

* Set up messaging channels: [Channels](https://agdiai-597e782f.mintlify.site/channels.md)
* Configure the Gateway: [Gateway configuration](https://agdiai-597e782f.mintlify.site/gateway/configuration.md)
* Keep Agdi up to date: [Updating](https://agdiai-597e782f.mintlify.site/install/updating.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.