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

​
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 the container port your service runs on
  3. Enter a path prefix (like /app or /api)
  4. Choose Public or Protected access
  5. Click Add Route
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 Pinata subdomain (like glow-kite-520.apps.pinata.cloud) or let you use your own domain. For a Pinata subdomain:
  1. Click + ADD → Subdomain tab
  2. Edit the generated subdomain name if you’d like (a random name is pre-filled)
  3. Enter the container port
  4. Choose Public or Protected access
  5. Click Register
For your own domain:
  1. Click + ADD → Custom Domain tab
  2. Enter your domain (like app.yourdomain.com)
  3. Enter the container port
  4. You’ll receive a TXT record challenge - add a TXT record at _pinata-verify.yourdomain.com with the provided value
  5. Save the domain registration
  6. Add a CNAME record pointing to the target shown after registration
  7. Click Verify to confirm ownership and provision SSL
After you click Verify, Pinata checks your TXT record to confirm you own the domain, then provisions SSL through Cloudflare. This can take a few minutes - your domain will show as “pending” until everything is ready.
The same domain always produces the same challenge token, so you only need to add the TXT record once even if you need to re-verify.

​
Editing and Removing Domains

Once a custom domain is created, you can update its target port and protected setting, but you cannot change the domain name or subdomain. To switch domains, delete and recreate.

​
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. Both path routes and custom domains default to public. Set them to protected explicitly if you need access control.
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)