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):

1. Open the Domains page in the Perceptron app
2. Click Reserve, enter a subdomain name (e.g. myapp → myapp.pct.site), and confirm
3. 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)
4. 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.

1. Open the Domains page in the Perceptron app and click Add Domain
2. Enter your domain (a leading www. is stripped; both example.com and www.example.com are served)
3. Publish the TXT record shown in the domain’s manage modal at your registrar (e.g. _perceptron-challenge.example.com with the given value), then press Verify Ownership
4. Point your A records at Perceptron: @ and (optionally) www to 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

API Authentication

Include your API key in the Authorization header:

Authorization: Bearer PERCEPTRON_API_KEY

Reservation

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.