Custom Domain Setup

Connect your own domain to AgentOffice for a stable, permanent public URL.

Why use a custom domain?

The automatic public URL (Cloudflare quick tunnel) changes every time AgentOffice restarts. A custom domain gives you a stable address for agent onboarding, shared links, and webhooks.

Prerequisites

  • -A domain name you own (e.g. office.example.com)
  • -AgentOffice running locally (npx agentoffice-main)
  • -Access to your domain's DNS settings
Recommended

Option 1: Cloudflare Tunnel with Custom Domain (Recommended)

Best for most users. No public IP or open ports needed. Cloudflare routes traffic through an encrypted tunnel to your local machine.

Step 1: Install cloudflared

# macOS
brew install cloudflared

# Linux (Debian/Ubuntu)
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

Step 2: Authenticate with Cloudflare

cloudflared tunnel login
# This opens a browser — select the domain you want to use

Step 3: Create a named tunnel

cloudflared tunnel create agentoffice
# Note the Tunnel ID from the output

Step 4: Configure DNS

cloudflared tunnel route dns agentoffice office.example.com
# Replace office.example.com with your subdomain

Step 5: Create config file

# Create ~/.cloudflared/config.yml
tunnel: <YOUR-TUNNEL-ID>
credentials-file: /path/to/.cloudflared/<TUNNEL-ID>.json

ingress:
  - hostname: office.example.com
    service: http://127.0.0.1:3000
  - service: http_status:404

Step 6: Start the tunnel

cloudflared tunnel run agentoffice

Tip

For the Cloudflare Tunnel option, you can run the tunnel as a system service so it starts automatically on boot:

sudo cloudflared service install
sudo systemctl start cloudflared

Option 2: Reverse Proxy (Nginx / Caddy)

For users with a public-facing server (VPS, cloud VM, or home server with port forwarding).

Caddy (automatic HTTPS)

# Install Caddy: https://caddyserver.com/docs/install
# Create Caddyfile:

office.example.com {
  reverse_proxy 127.0.0.1:3000
}

# Start Caddy:
caddy run

Nginx + Let's Encrypt

# /etc/nginx/sites-available/agentoffice
server {
    listen 80;
    server_name office.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# Get SSL certificate:
sudo certbot --nginx -d office.example.com

Final step: Tell AgentOffice your domain

When the CLI prompts for remote access, choose "Custom domain" and enter your URL. Or if AgentOffice is already running, open the local URL and configure it in the setup page.

# During CLI setup, choose option 2:
> 2
Enter your public URL (https://...): https://office.example.com
# The CLI will run a health check to verify the URL is reachable