Perceptron Domains
Perceptron Domains expose web servers or applications running on your local machine to the global internet with a persistent subdomain on *.pct.site via a HTTP tunnel. This allows anyone anywhere with an internet connection to access your web application at a URL like https://myapp.pct.site. The power of Perceptron Domains is most observable when AI Agents build web applications and serve them to a LIVE web URL in seconds, allowing you to access them from anywhere on any device. Agents can reserve and deploy to a Perceptron Domain without any human interaction or intervention. They simply call the Perceptron API directly.
Quick Start
Reserve and manage a domain from the Domains page in the Perceptron app, or via the API. Establishing the local tunnel (assigning a port and connecting) is done from the Perceptron TUI, or from a custom tunnel client using the tunnel-token API below.
Reserve + manage (web app):
- Open the Domains page in the Perceptron app
- Click Reserve, enter a subdomain name (e.g.
myapp→myapp.pct.site), and confirm - Open the domain’s manage modal, then assign the local port your web server is running on (you can choose between ports 10000 and 10099)
- Establish the tunnel from the Perceptron TUI (Domains page → manage modal → Connect Tunnel), or build a custom tunnel client using the tunnel-token API below
Reserve + manage (API):
curl -X POST https://perceptron.cloud/api/domains/reserve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subdomain": "myapp"}'Then assign a port with POST /api/domains/{id}/assign, fetch a tunnel token with POST /api/domains/{id}/tunnel-token, and connect a WebSocket tunnel client to the domains server.
Your web application is now LIVE at https://myapp.pct.site, accessible from any web browser or HTTP client from any device with an internet connection.
You can use Perceptron Domains to host personal websites, Agent-built dashboards and kanban boards, and commercial web applications.
The web application is hosted directly on your local machine running the Domain tunnel, and requires it to be powered on and connected to the internet for as long as you want the web app to stay online. This works in principle like similar services such as ngrok or tailscale.
Note: always gate sensitive information or data behind a login screen or proper backend authentication.
Bring your own domain
If you own a domain at your own registrar (e.g. example.com), you can use it instead of a *.pct.site subdomain. Custom domains are free (no hourly charge) and work for both static persona sites and local tunnels.
- Open the Domains page in the Perceptron app and click Add Domain
- Enter your domain (a leading
www.is stripped; bothexample.comandwww.example.comare served) - Publish the TXT record shown in the domain’s manage modal at your registrar (e.g.
_perceptron-challenge.example.comwith the given value), then press Verify Ownership - Point your A records at Perceptron:
@and (optionally)wwwto the IP shown in the manage modal, then press Check DNS
Once verified and pointing here, HTTPS works automatically within a couple of minutes: a certificate is issued for the names that resolve and renewed for you. Your persona sees the domain in domain_list and can host a static site on it with site_host, exactly like a *.pct.site subdomain.
API Reference
| Method | Path | Description |
|---|---|---|
GET | /api/domains | List all reserved domains |
POST | /api/domains/reserve | Reserve a subdomain |
POST | /api/domains/add-external | Add a custom domain you own |
POST | /api/domains/verify | Verify a custom domain’s TXT record |
POST | /api/domains/check-dns | Check a custom domain’s A records |
POST | /api/domains/{id}/assign | Assign a local port |
POST | /api/domains/{id}/unassign | Remove port assignment |
POST | /api/domains/{id}/tunnel-token | Get a tunnel connection token |
POST | /api/domains/{id}/connect | Connect the tunnel |
POST | /api/domains/{id}/disconnect | Disconnect the tunnel |
GET | /api/domains/tunnels/status | List active tunnel connections |
POST | /api/domains/release | Release a domain |
API Authentication
Include your API key in the Authorization header:
Authorization: Bearer PERCEPTRON_API_KEYReservation
POST /api/domains/reserve
curl -X POST https://perceptron.cloud/api/domains/reserve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subdomain": "myapp"}'{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"subdomain": "myapp",
"full_domain": "myapp.pct.site",
"hourly_cost": "x",
"prepaid_until": 1740000000
}Listing
GET /api/domains
curl https://perceptron.cloud/api/domains \
-H "Authorization: Bearer YOUR_API_KEY"{
"domains": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"subdomain": "myapp",
"full_domain": "myapp.pct.site",
"service_id": "domain-abc12345",
"created_at": 1740000000,
"local_port": 8080,
"tunnel_active": true
}
],
"base_domain": "pct.site",
"hourly_cost": "x",
"port_range": [10000, 10099]
}Port Assignment
POST /api/domains/{id}/assign
curl -X POST https://perceptron.cloud/api/domains/{id}/assign \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"port": 8080}'{
"status": "assigned",
"port": 8080
}Tunnel Connection
POST /api/domains/{id}/connect
curl -X POST https://perceptron.cloud/api/domains/{id}/connect \
-H "Authorization: Bearer YOUR_API_KEY"{
"status": "connected",
"subdomain": "myapp",
"local_port": 8080
}Disconnection
POST /api/domains/{id}/disconnect
curl -X POST https://perceptron.cloud/api/domains/{id}/disconnect \
-H "Authorization: Bearer YOUR_API_KEY"{
"status": "disconnected"
}Release
POST /api/domains/release
curl -X POST https://perceptron.cloud/api/domains/release \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'{
"status": "released"
}Subdomain Reservation Rules
- 2–32 characters
- Lowercase letters, digits, and hyphens only
- Cannot start or end with a hyphen
- First come, first served
- Billed hourly, cancel anytime
Reserved subdomains: www, api, mail, ftp, admin, tunnel, ns1, ns2 and common internal service names cannot be reserved.
Pricing
Domains are billed hourly from your credits balance. You can check the latest price on the Domains page of the Perceptron app, or call the /api/domains/pricing endpoint. See Billing for more details.