Render Private Services
Private services are identical to web services except they have no public URL. They are reachable only by other Render services on the same private network (same region + workspace). Use them for internal APIs, microservices, gRPC servers, sidecar processes, and anything that should never face the internet.
When to Use
- Building an internal API or microservice behind a public gateway
- Running a gRPC, TCP, or other non-HTTP server that only your services call
- Deploying infrastructure components (Elasticsearch, ClickHouse, RabbitMQ)
- Choosing between a private service and a background worker
For public-facing HTTP services, use render-web-services. For services that don't receive any traffic, use render-background-workers.
Private Service vs Background Worker
| Criterion |
Private Service |
Background Worker |
| Binds to a port |
Yes (required) |
No |
| Receives private network traffic |
Yes |
No |
| Sends outbound traffic |
Yes |
Yes |
| Has internal hostname |
Yes |
No |
| Use case |
Internal APIs, gRPC, TCP servers |
Queue consumers, async processors |
Rule of thumb: If the process listens on a port and other services call it, it's a private service. If it pulls work from a queue and never receives requests, it's a background worker.
How Private Services Work
- No
onrender.com subdomain—not reachable from the internet
- Reachable at
<service-name>:<port> on the private network by services in the same region and workspace
- Can listen on any port (except restricted system ports)—not limited to HTTP or port 10000
- Supports any protocol: HTTP, gRPC, TCP, WebSocket, custom binary protocols
- Same build/deploy lifecycle as web services (build command, start command, pre-deploy, health checks via the private network)
- Supports persistent disks, scaling, Docker runtime—same capabilities as web services
Connecting to a Private Service
Other services reference a private service via its internal hostname and port:
http://<service-name>:<port>
In Blueprints, wire the address using fromService:
- key: INTERNAL_API_URL
fromService:
name: my-api
type: pserv
property: hostport
Available fromService properties for pserv:
| Property |
Value |
host |
Internal hostname (e.g. my-api) |
port |
Port the service listens on |
hostport |
host:port combined (e.g. my-api:10000) |
You can also reference a specific env var from the private service using envVarKey instead of property.
Port Binding
Private services must bind to at least one port. If your process does not need to receive traffic, create a background worker instead.
- Bind to
0.0.0.0 (not 127.0.0.1 or localhost)
- The
PORT env var defaults to 10000, but you can listen on any non-restricted port
- For non-HTTP protocols (gRPC, TCP), configure your server on the desired port and tell consumers the
hostport
Blueprint Configuration
services:
- type: pserv
name: internal-api
runtime: node
region: oregon
plan: starter
buildCommand: npm ci && npm run build
startCommand: npm start
envVars:
- key: DATABASE_URL
fromDatabase:
name: db
property: connectionString
Microservices pattern (gateway + internal services)
services:
- type: web
name: gateway
runtime: node
plan: starter
region: oregon
buildCommand: npm ci && npm run build
startCommand: npm start
envVars:
- key: USER_SERVICE_URL
fromService:
name: user-service
type: pserv
property: hostport
- key: BILLING_SERVICE_URL
fromService:
name: billing-service
type: pserv
property: hostport
- type: pserv
name: user-service
runtime: node
plan: starter
region: oregon
buildCommand: npm ci
startCommand: node server.js
envVars:
- key: DATABASE_URL
fromDatabase:
name: db
property: connectionString
- type: pserv
name: billing-service
runtime: python
plan: starter
region: oregon
buildCommand: pip install -r requirements.txt
startCommand: gunicorn billing:app
envVars:
- key: DATABASE_URL
fromDatabase:
name: db
property: connectionString
References
| Document |
Contents |
references/patterns.md |
Microservice topology, gRPC setup, sidecar patterns, health checks for private services |
Related Skills
- render-web-services — Public HTTP services
- render-networking — Private network, DNS, service discovery
- render-background-workers — Services that don't receive traffic
- render-blueprints — Full
render.yaml schema, fromService wiring
- render-scaling — Instance types and autoscaling for private services
1---2name: render-private-services3description: Configures Render private services—internal-only apps that accept traffic exclusively from other Render services over the private network. Use when the user needs an internal API, microservice, gRPC server, sidecar, or any service that should not be publicly accessible. Also use when choosing between a private service and a background worker. Trigger terms: private service, pserv, internal service, internal API, microservice, gRPC, not public, private network service.4license: MIT5---67# Render Private Services89Private services are identical to web services except they have **no public URL**. They are reachable only by other Render services on the same **private network** (same region + workspace). Use them for internal APIs, microservices, gRPC servers, sidecar processes, and anything that should never face the internet.1011## When to Use1213- Building an **internal API** or **microservice** behind a public gateway14- Running a **gRPC**, **TCP**, or other non-HTTP server that only your services call15- Deploying infrastructure components (**Elasticsearch**, **ClickHouse**, **RabbitMQ**)16- Choosing between a **private service** and a **background worker**1718For public-facing HTTP services, use **render-web-services**. For services that don't receive any traffic, use **render-background-workers**.1920## Private Service vs Background Worker2122| Criterion | Private Service | Background Worker |23|-----------|----------------|-------------------|24| Binds to a port | **Yes** (required) | No |25| Receives private network traffic | **Yes** | No |26| Sends outbound traffic | Yes | Yes |27| Has internal hostname | **Yes** | No |28| Use case | Internal APIs, gRPC, TCP servers | Queue consumers, async processors |2930**Rule of thumb:** If the process **listens on a port** and other services call it, it's a private service. If it **pulls work from a queue** and never receives requests, it's a background worker.3132## How Private Services Work3334- No `onrender.com` subdomain—not reachable from the internet35- Reachable at `<service-name>:<port>` on the private network by services in the same region and workspace36- Can listen on **any port** (except restricted system ports)—not limited to HTTP or port 1000037- Supports **any protocol**: HTTP, gRPC, TCP, WebSocket, custom binary protocols38- Same build/deploy lifecycle as web services (build command, start command, pre-deploy, health checks via the private network)39- Supports persistent disks, scaling, Docker runtime—same capabilities as web services4041## Connecting to a Private Service4243Other services reference a private service via its **internal hostname and port**:4445```46http://<service-name>:<port>47```4849In Blueprints, wire the address using `fromService`:5051```yaml52- key: INTERNAL_API_URL53 fromService:54 name: my-api55 type: pserv56 property: hostport57```5859Available `fromService` properties for `pserv`:6061| Property | Value |62|----------|-------|63| `host` | Internal hostname (e.g. `my-api`) |64| `port` | Port the service listens on |65| `hostport` | `host:port` combined (e.g. `my-api:10000`) |6667You can also reference a specific env var from the private service using `envVarKey` instead of `property`.6869## Port Binding7071Private services **must bind to at least one port**. If your process does not need to receive traffic, create a background worker instead.7273- Bind to `0.0.0.0` (not `127.0.0.1` or `localhost`)74- The `PORT` env var defaults to `10000`, but you can listen on any non-restricted port75- For non-HTTP protocols (gRPC, TCP), configure your server on the desired port and tell consumers the `hostport`7677## Blueprint Configuration7879```yaml80services:81 - type: pserv82 name: internal-api83 runtime: node84 region: oregon85 plan: starter86 buildCommand: npm ci && npm run build87 startCommand: npm start88 envVars:89 - key: DATABASE_URL90 fromDatabase:91 name: db92 property: connectionString93```9495### Microservices pattern (gateway + internal services)9697```yaml98services:99 - type: web100 name: gateway101 runtime: node102 plan: starter103 region: oregon104 buildCommand: npm ci && npm run build105 startCommand: npm start106 envVars:107 - key: USER_SERVICE_URL108 fromService:109 name: user-service110 type: pserv111 property: hostport112 - key: BILLING_SERVICE_URL113 fromService:114 name: billing-service115 type: pserv116 property: hostport117118 - type: pserv119 name: user-service120 runtime: node121 plan: starter122 region: oregon123 buildCommand: npm ci124 startCommand: node server.js125 envVars:126 - key: DATABASE_URL127 fromDatabase:128 name: db129 property: connectionString130131 - type: pserv132 name: billing-service133 runtime: python134 plan: starter135 region: oregon136 buildCommand: pip install -r requirements.txt137 startCommand: gunicorn billing:app138 envVars:139 - key: DATABASE_URL140 fromDatabase:141 name: db142 property: connectionString143```144145## References146147| Document | Contents |148|----------|----------|149| `references/patterns.md` | Microservice topology, gRPC setup, sidecar patterns, health checks for private services |150151## Related Skills152153- **render-web-services** — Public HTTP services154- **render-networking** — Private network, DNS, service discovery155- **render-background-workers** — Services that don't receive traffic156- **render-blueprints** — Full `render.yaml` schema, `fromService` wiring157- **render-scaling** — Instance types and autoscaling for private services
ConcertoNotes