Skip to main content
If your agent runs a web server, API, or any other network service, routes let you expose it to the internet. Your agent’s container is isolated by default — routes punch a hole through so the outside world can reach your service.

​
When You Need Routes

Common use cases:
  • Your agent runs a web app (React, Vue, etc.) and you want users to access it
  • Your agent exposes an API that other services need to call
  • You’re running a dev server with hot reload and need external access
If your agent just chats and runs scripts, you probably don’t need routes.

​
Add a Route

Open your agent → Routes → ADD. You have two options: Path Route or Custom Domain.

​
Path Routes

Path routes are the simplest option. Your service becomes available at a URL like: 
https://agents.pinata.cloud/v0/agents/{agentId}/app/...
To set one up:
  1. Click ADD → Path Route
  2. Enter a path prefix (like /app or /api)
  3. Enter the port your service runs on inside the container
  4. Choose whether it’s protected or public
  5. Save
One thing to know: the path prefix gets stripped before reaching your service. If someone requests /app/users/123, your service sees /users/123.

​
Custom Domains

Custom domains are currently in beta.
Want a cleaner URL? Custom domains give you either a random Pinata subdomain (like swift-fox-347.apps.pinata.cloud) or let you use your own domain. For a Pinata subdomain:
  1. Click ADD → Custom Domain → Pinata Subdomain
  2. Enter the port
  3. Choose protected or public
  4. Save — you’ll get a random subdomain instantly
For your own domain:
  1. Click ADD → Custom Domain → Bring Your Own
  2. Enter your domain (like app.yourdomain.com)
  3. Enter the port
  4. Save
  5. Add the DNS records shown (a TXT record for verification, then a CNAME)
Your domain will show as “pending” until DNS propagates and SSL is provisioned.

​
Protected vs Public

Protected routes require a gateway token to access. Use this when you want to control who can reach your service. Public routes are open to anyone on the internet. Only use this if your service handles its own authentication, or if you genuinely want it public.
Think carefully before making a route public. Anyone can access it.

​
Limits

  • Up to 10 path routes per agent
  • Up to 5 custom domains per agent
  • Ports must be between 1025 and 65535 (port 18789 is reserved)