Deploy: Preview vs Production
By the end of this page you will know how to create deployments, understand the difference between preview and production environments, and manage deployment lifecycle.
Prerequisites
- A Task Agent in PRODUCTION status (Versioning & promotion).
- Admin role.
Understanding deployments
A deployment is a running environment that makes your agents and apps accessible at a unique URL. Each deployment has:
- Name — A unique identifier (e.g., “resolution-agent”).
- URL — Auto-generated subdomain (e.g.,
resolution-agent.dev.qraptor.app). - Type — Copilot, Web App, or API.
- Version — The deployment’s own version number.
- Status — Ready, Deploying, Failed, or Stopped.
- Channels — What’s enabled (Application Service, Chat Widget, Agents).
- Authentication — API Keys, OIDC, or both.
The Deployments page
Navigate to Deployments in the project sidebar. The page shows all active deployments as cards with:
- Deployment name and type badge
- Status indicator (Ready = green)
- Live URL with an external link icon
- Enabled channels (Application Service, Chat Widget, Agents)
- Authentication methods
- Last activity timestamp
Creating a deployment
Click Deploy
On the Deployments page, click the Deploy button in the top-right. A dropdown shows deployment type options.
Choose the deployment type
Select the type of deployment:
| Type | Best for |
|---|---|
| Copilot | AI assistant with a chat widget interface |
| Web App | Full application with custom UI |
| API | Headless API endpoint for integrations |
Configure the deployment
Fill in the deployment settings:
- Name — Used in the URL (e.g., “my-agent” becomes
my-agent.dev.qraptor.app). - Agents — Select which agents to include in this deployment.
- Authentication — Choose API Keys, OIDC, or both.
- Channels — Enable Application Service, Chat Widget, and/or Agent-to-Agent.
Deploy
Click Create to launch the deployment. Status changes from “Deploying” to “Ready” once provisioning completes (typically within a few seconds).
Preview vs Production environments
qRaptor uses the dev.qraptor.app subdomain for preview/development deployments. Production deployments can use custom domains (see Custom domains).
| Aspect | Preview | Production |
|---|---|---|
| URL | *.dev.qraptor.app | Custom domain or *.qraptor.app |
| Purpose | Testing and internal use | End-user traffic |
| Rate limits | Lower | Higher (plan-dependent) |
| SLA | Best-effort | Per your plan |
Deployments are updated in place when you add or remove agents. No redeployment is needed when you promote a new agent version — the deployment automatically uses the latest PRODUCTION version.
Managing deployments
Viewing deployment details
Click a deployment card to view its full configuration, connected agents, API keys, and activity log.
Updating a deployment
From the deployment detail view, you can:
- Add or remove agents
- Regenerate API keys
- Enable/disable channels
- Update authentication settings
Stopping a deployment
Click the three-dot menu on a deployment card and select Stop. The deployment URL becomes inactive. You can restart it later without losing configuration.
Common issues
- “Deployment stuck in Deploying” — Wait up to 60 seconds. If it doesn’t resolve, check that your project has available deployment slots.
- “URL not reachable” — DNS propagation can take a few minutes for new deployments. Try again shortly.
- “401 Unauthorized” — Verify you’re using a valid API key or OIDC token for the deployment.
- “Agent not responding” — Ensure the agent is in PRODUCTION status and has been added to the deployment.