Skip to main content

Pointing at a Private Deployment

By default, the firmware connects to Espressif's hosted production gateway at api.agents.espressif.com. To make a device connect to your own private deployment instead, you change a Kconfig setting and re-flash.

This is for organizations running their own ESP Private Agents deployment.

What you need​

  • A working ESP-IDF build environment (see Build from Source).
  • The API URL of your deployment — typically api.<deployment-prefix>.evaluation.esp-private-agents.com (e.g., api.bxmqxnlxtx.evaluation.esp-private-agents.com) or, if you've set up a custom domain, api.agent.yourcompany.com (or similar).
  • A refresh token for an end-user account on your deployment.

Get a refresh token​

  1. Sign in to your deployment's User Dashboard.
  2. Click your Profile.
  3. Click Copy Refresh Token.
  4. Save the token — you'll paste it into the device.

This token lets the device authenticate to your gateway. Treat it like a password.

Steps​

1. Change the gateway URL​

cd examples/voice_chat   # or matter_controller
idf.py menuconfig

Navigate to:

ESP Agent Config
  ── ESP Private Agents Server URL

Change the value from wss://api.agents.espressif.com to your URL — for example wss://api.bxmqxnlxtx.evaluation.esp-private-agents.com. Keep the wss:// scheme. Save (s), exit (q).

2. Build and flash​

idf.py build flash monitor

3. Pair Wi-Fi via the mobile app​

Wi-Fi credentials are provisioned by the ESP RainMaker Home mobile app over BLE/SoftAP. Follow the standard pairing flow described in Install & Pair — the device shows up as a new accessory and you join it to your Wi-Fi from the app.

The device only needs Wi-Fi to reach your gateway; it doesn't matter that the agent isn't assigned yet.

4. Configure the refresh token and agent over serial​

After the device is on Wi-Fi, the serial monitor shows a prompt. Type:

set-token <your-refresh-token>
set-agent <agent-id>

The device authenticates with your gateway using the refresh token and pulls down the agent config.

4. Verify​

Wake the device and have a quick conversation. If it replies, you're connected to your gateway.

Using the mobile app instead​

The QR-pair flow in ESP RainMaker Home doesn't currently support custom gateway endpoints — it assumes Espressif's hosted platform. So for private deployments, the serial-console path above is the way.

Once the device is configured to point at your gateway, you can still use the mobile app for:

  • Reprovisioning Wi-Fi.
  • Scanning agent QRs from your own Admin Dashboard to swap agents.

What about devices in the field?​

The gateway URL is baked in at build time, so a device flashed against Espressif's hosted gateway has to be reflashed with a build that has CONFIG_ESP_AGENT_SERVER_URL set to your deployment. The token and agent ID can then be updated over serial without another reflash.

Troubleshooting​

SymptomLikely cause
Device boots but never connectsWrong server URL, or the URL is missing the wss:// scheme.
"Authentication failed" in monitorRefresh token is wrong, expired, or for the wrong deployment.
Device connects but says "agent not found"The agent ID doesn't exist on this deployment, or the user account doesn't have access.
Connection works but silent (no chime on wake)Wake-word config is fine but agent assignment is wrong. Re-run set-agent.

Token rotation​

Refresh tokens can be rotated on the platform. After rotation, the device's old token stops working — re-run set-token <new-token> over serial.

For deployments with many devices, consider:

  • Keeping tokens long-lived, or
  • Embedding a service-account-style token at build time (custom Kconfig fragment) — requires firmware modification.

Why two configs?​

The gateway URL is a Kconfig string — it's compiled into the firmware image. The token, agent ID, and Wi-Fi credentials are runtime because they're per-user, per-deployment, and per-network. That split is why pointing at a private deployment requires a reflash, but switching agents or rotating tokens does not.

On this page