---
title: Deploy on Render
---

Deploy Moltbot 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](/providers)

## Alternative: Wrapper with Installer

For a deployment with a built-in installer and proxied Control UI (including WebSocket support), see community wrappers (e.g. in the ecosystem docs). Such wrappers may provide:

- **Install Wizard** at `/install` (password protected)
- **Control UI** reverse-proxied with WebSocket support
- **Export / Import backups** to migrate deployments

## Deploy with a Render Blueprint

<a href="https://render.com/deploy?repo=https://github.com/moltbot/moltbot" target="_blank" rel="noreferrer">Deploy to Render</a>

Clicking this link will:

1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
2. Prompt you to set `MOLTBOT_GATEWAY_TOKEN` (or set it in **Environment** after deploy).
3. 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 Moltbot:

```yaml
services:
  - type: web
    name: moltbot
    runtime: docker
    plan: starter
    dockerCommand: /bin/sh scripts/render-start.sh
    envVars:
      - key: PORT
        value: "8080"
      - key: MOLTBOT_GATEWAY_TOKEN
        sync: false          # set in Render dashboard (secret)
      - key: MOLTBOT_STATE_DIR
        value: /data/.moltbot
      - key: MOLTBOT_WORKSPACE_DIR
        value: /data/workspace
      # LLM Provider API Keys (set these in Render dashboard as secrets)
      - key: ANTHROPIC_API_KEY
        sync: false
      - key: OPENAI_API_KEY
        sync: false
      - key: GEMINI_API_KEY
        sync: false
      - key: GROQ_API_KEY
        sync: false
      - key: OPENROUTER_API_KEY
        sync: false
      # Add other provider keys as needed (MISTRAL_API_KEY, XAI_API_KEY, etc.)
    disk:
      name: moltbot-data
      mountPath: /data
      sizeGB: 1
```

Key Blueprint features used:

| Feature | Purpose |
|---------|---------|
| `runtime: docker` | Builds from the repo's Dockerfile |
| `dockerCommand` | Runs `scripts/render-start.sh` to create config and start the gateway |
| `sync: false` | Prompts for value during deploy (secrets) |
| `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

### Set the gateway token

1. In Render **Dashboard → your service → Environment**, set `MOLTBOT_GATEWAY_TOKEN` to a long random secret (or generate one with `openssl rand -hex 32`).
2. Save changes; Render will redeploy.

### Access the Control UI

The web dashboard is at `https://<your-service>.onrender.com/moltbot`. Open a tokenized URL (e.g. from the service logs or your own link that includes the token) or paste the token into the Control UI settings to authenticate.

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

#### Configuring LLM API Keys

After deployment, you need to configure at least one LLM provider API key. Set these in the Render dashboard:

**Most common providers:**

- **Anthropic (Claude)**: `ANTHROPIC_API_KEY` — Get from [Anthropic Console](https://console.anthropic.com/)
- **OpenAI (GPT)**: `OPENAI_API_KEY` — Get from [OpenAI Platform](https://platform.openai.com/api-keys)
- **Google Gemini**: `GEMINI_API_KEY` — Get from [Google AI Studio](https://aistudio.google.com/app/apikey)
- **Groq**: `GROQ_API_KEY` — Get from [Groq Console](https://console.groq.com/keys)
- **OpenRouter**: `OPENROUTER_API_KEY` — Get from [OpenRouter](https://openrouter.ai/keys)

**Additional providers:**

- `MISTRAL_API_KEY` — Mistral AI
- `XAI_API_KEY` — xAI (Grok)
- `OPENCODE_API_KEY` — OpenCode Zen
- `DEEPGRAM_API_KEY` — Deepgram (speech-to-text)

To set API keys:

1. Go to **Dashboard → your service → Environment**
2. Click **Add Environment Variable**
3. Enter the variable name (e.g., `ANTHROPIC_API_KEY`)
4. Enter your API key value
5. Click **Save Changes**

The service will automatically redeploy with the new environment variable.

**Alternative: Config file method**

You can also configure API keys in the `moltbot.json` config file (under `MOLTBOT_STATE_DIR` or `~/.moltbot`) using the `env` block, though environment variables are preferred for security:

```json5
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "OPENAI_API_KEY": "sk-..."
  }
}
```

See [Model Providers](/concepts/model-providers) for a complete list of supported providers and their configuration.

### Auto-deploy

If you use a fork, Render will not auto-deploy from the upstream repo. To update, run a manual Blueprint sync from the dashboard or push to your connected branch.

## 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 Moltbot, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.

## Backups and migration

If your deployment exposes a setup/export endpoint, you can export configuration and workspace from:

```
https://<your-service>.onrender.com/setup/export
```

Otherwise, backup the persistent disk contents (e.g. under `/data/.moltbot`) via Render Shell or your own backup process.

## Troubleshooting

### Service won't start

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

- Missing `MOLTBOT_GATEWAY_TOKEN` — set it in **Environment** (Dashboard → your service → Environment)
- Port mismatch — ensure `PORT=8080` matches the gateway port

### 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 `/setup/export`.

### Health check failures

If Render is configured with `healthCheckPath: /health`, it expects a 200 from `/health` within 30 seconds. This blueprint does not set a health check by default. If deploys fail, check deploy logs and that `scripts/render-start.sh` runs correctly (config written under `MOLTBOT_STATE_DIR` or `~/.moltbot`, then gateway started with the token).