Migrate from Amazon Q Business to Onyx

Migrate from Amazon Q Business to Onyx: what the move involves

Moving off a closed Amazon Q Business application is mostly connector, permission and model work, not a bulk data export. Your documents stay in S3, SharePoint, Confluence, Salesforce and other systems of record, and Onyx re-reads them through its own connectors. The effort depends on how many data sources the application indexes, how many Q Apps and guardrails your users rely on, and how much of your identity setup has to be rebuilt. Start by running the AWS CLI inventory of the application's data sources, plugins, user groups and any Q Apps, then mark each item as reconnect, rebuild or retire.

Permissions need the most care. Q Business enforces access through IAM Identity Center and the source systems' own ACLs, so Onyx has to reproduce that position through its connector permission sync and SSO. Configure Google OAuth, OIDC or SAML for sign-in, provision users with SCIM where your identity provider supports it, and then test with real accounts from each group that a user cannot retrieve a document they could not open in the source system. Expect the first tests to surface stale groups, service accounts with broad read access and Salesforce sharing rules that do not map cleanly. Q Apps and guardrails have no one-to-one equivalent, so their behavior must be rewritten as Onyx agents, actions and content policy you define and test.

Platform and security teams usually own this work, often with an implementation partner for connector setup, permission validation and hardening. Model choice is a separate decision: Onyx can call hosted providers or self-hosted models through Ollama, LiteLLM or vLLM, and that choice changes data flows and operating cost. The main risk is a permission gap that goes unnoticed until someone sees content they should not. Plan a parallel run, keep the Q Business application available until access tests pass, and confirm current Onyx release and connector details in the Onyx GitHub repository before you commit to a version.

Which Amazon Q Business capabilities map cleanly to Onyx

This table maps each main Amazon Q Business capability to its closest Onyx equivalent and marks it as clean, needs rework or gap. Read the status column first, then the Onyx cell to see what must be confirmed or rebuilt. Permission-aware search and connectors map most directly, while Q Apps and guardrails need redesign.

Capability	Onyx equivalent	Status
Permission-aware search over company data	Onyx syncs permissions from 50+ connected applications, so answers only draw on documents the user can already see in the source system	Clean
Data source connectors (S3, SharePoint, Confluence, Salesforce)	Onyx ships connectors for SharePoint, OneDrive, Confluence, Salesforce and other sources. S3 is not in the cited connector list, so confirm it in the Onyx connectors directory before planning	Needs rework
SSO and identity (IAM Identity Center)	Google OAuth, OIDC or SAML single sign-on and SCIM user provisioning. Confirm your identity provider's SAML or OIDC setup against the Onyx docs for your edition	Needs rework
Chat and agents	Onyx Community Edition covers AI chat, agents and actions under the MIT license. Confirm which agent features your chosen edition includes	Clean
Q Apps (generative app builder)	No direct equivalent is cited. Rebuild each Q App as an Onyx agent or a separate application that calls your model endpoint	Gap
Guardrails and content controls	Not documented as a one-to-one feature. Plan controls at the model gateway (such as LiteLLM) and in Onyx access rules, and test them before cutover	Gap
Model choice	Onyx works with Ollama, LiteLLM and vLLM for self-hosted models, plus Anthropic, OpenAI and Gemini. Confirm which Bedrock-hosted models you need and how to route them	Needs rework
Admin controls and role-based access	Role-based access control is listed as an Enterprise Edition feature. Confirm whether the Community Edition meets your admin needs	Needs rework
Usage analytics and query history audit	Query history auditing and usage analytics are listed among Onyx enterprise features. Confirm export format and retention with the Onyx docs	Needs rework

What moves cleanly and what must be rebuilt

Your source content does not come out of Amazon Q Business as a portable export, so plan to re-index it from the original systems. Q Business builds its own index, and the documents you need sit in S3 buckets, SharePoint, Confluence and Salesforce. In Onyx you reconnect each of those sources with its connector, and the index is rebuilt from the source applications. This matters for permissions. Onyx syncs the access rights of each source, so answers draw only on documents the user can already see in the original application. Do not expect to copy the Q Business index across and treat its access rules as still valid. Before you start, ask AWS which export options exist for Q Business application configuration, and confirm them in writing, because this changes what you can carry over as settings rather than rebuilt by hand.

Start the inventory with the AWS CLI, recording every data source and its sync schedule, every plugin or action, the identity configuration (IAM Identity Center or other identity source, and which user groups map to which applications), every Q App, and every guardrail or content rule. Keep the output of each command with its date, because the configuration may change while the project runs. Q Apps and guardrail logic should not be ported line for line. A Q App is a workflow tied to Q Business features, so you redesign it as an Onyx agent with its own tools and prompts. Guardrail rules become access rules and topic restrictions that you define and test in Onyx. For each item, record its owner and the business process it supports. Some items will be dropped on purpose. Treat the rebuild as a design exercise and test each agent and access rule against real user accounts before cutover.

Which data sources and integrations to reconnect in Onyx

Amazon Q Business answered from the sources you connected to it, and its users saw only what their identity could already open. In Onyx, each reconnected source needs its own connector, its own credentials and a permission sync check, so the cards below cover each class of integration you must rebuild and verify before cutover.

S3 buckets

Start from the data source inventory you pulled with the AWS CLI, and list every bucket and prefix that Q Business indexed. Recreate read access for Onyx with a dedicated IAM role scoped to those prefixes, rather than reusing the Q Business service role. Confirm in the Onyx connector documentation whether S3 access control follows bucket policies or object metadata, because Q Business document-level permissions may not carry over as-is and need a separate mapping.

SharePoint and OneDrive

These are the sources where permission sync matters most. Onyx draws answers only from documents the user can already see in the source application, so register an Entra app with the Graph permissions the connector requires and confirm that sync covers site, library and item-level permissions. Test with two users who hold different access before you trust the results, and check how group membership changes propagate after a user leaves a team.

Confluence

Confluence spaces and page restrictions often diverge from the Atlassian groups that Q Business relied on. Inventory which spaces were indexed, then confirm with your Atlassian administrator which restrictions apply to pages and which apply to whole spaces. Verify in Onyx that restricted pages stay hidden from users outside the permitted group, and re-check after your first full sync, since restriction changes made in Confluence only reach Onyx on a later sync.

Salesforce

Salesforce access depends on profiles, permission sets and sharing rules, which are harder to mirror than folder permissions. Create a dedicated integration user with read-only access to the objects you need, and document which objects and fields were in scope under Q Business. Confirm with your Salesforce administrator whether the Onyx connector honors record-level sharing, and test with a user whose sharing is narrower than the integration user's.

Identity, SSO and SCIM

Q Business used IAM Identity Center, so your users, groups and attributes must map cleanly to Onyx. Configure SSO through Google OAuth, OIDC or SAML, then set up SCIM provisioning so deprovisioned users lose access in Onyx without manual cleanup. Confirm which group attributes the SCIM feed sends, because role-based access control in Onyx Enterprise Edition depends on them, and test a leaver account end to end.

Model providers

Q Business hid its underlying models, so you must choose and connect new ones. Onyx supports self-hosted models through Ollama, LiteLLM and vLLM, as well as Anthropic, OpenAI and Gemini. Decide where prompts may travel, store each provider key in a secrets manager, and confirm with your data protection team whether any provider terms or regional settings conflict with your residency rules before you route production traffic.

Migration sequence from inventory to decommission

This sequence moves Amazon Q Business users onto a self-hosted Onyx deployment in five controlled stages, so each change is tested with real permissions before anyone depends on it. Each step ends with a written artifact that the next step and the eventual decommission decision rely on.

Inventory every Q Business component
Use the AWS CLI to list the Q Business application, its data source connectors, index configuration, web experiences, plugins, Q Apps, guardrails, and the identity source tied to IAM Identity Center. Record each item in an integration register with its owner, its source system, the document count where the CLI or console reports it, and whether it has a direct Onyx connector, a workaround, or no equivalent. Confirm the exact subcommands and output fields against the current AWS CLI reference for your version, since the output shape varies. The step is done when every data source and every user-facing feature has a row in the register and the gaps are listed for a decision.
Build a pilot connector set and test permissions
Stand up Onyx in a non-production environment inside your own cloud account or data center, then connect a small set of sources that match the highest-value entries in the register, such as SharePoint, Confluence or S3 where a connector applies. Onyx syncs source permissions, so run a permission test with several named test accounts at different access levels, comparing what each account can retrieve in Onyx against what it can open in the source application. Document each mismatch and its fix. The output is a permission test report that shows zero answers drawn from documents the test user cannot already see in the source system, and sign-off from the data owners of each pilot source.
Run a parallel period with a defined group
Choose a named user group, such as one business unit or a team that already uses Q Business daily, and let them use both assistants for an agreed period. Ask them to run a fixed set of representative questions on both platforms and to log answers that are wrong, missing, or exposed beyond their permissions. Track model behavior too, since Onyx can route to self-hosted models through Ollama, LiteLLM or vLLM or to proprietary providers, and the output quality depends on that choice. The step closes with a parallel run log, a list of accepted gaps with owners, and a go or no-go decision recorded by the sponsor.
Cut over with a runbook and user communication
Write a cutover runbook covering the final source sync, the change to user access paths, the rollback steps to the Q Business application, the support contact for the first weeks, and the handling of any Q Apps or guardrail behavior that was accepted as a gap. Tell users in advance what changes, which questions no longer work the same way, and where to report problems. Expand connectors to the remaining sources only after the runbook has been executed in a rehearsal. The output is a signed cutover runbook, a rehearsal record, and a communication sent to all affected users.
Retain evidence and decommission Q Business
Once the cutover has run without rollback for the agreed stabilization window, export the final integration register, permission test reports, parallel run log and runbook, and store them where your compliance team can access them. Confirm that no users, applications, or data sources still depend on the Q Business application, then remove or disable it and delete the associated IAM Identity Center configuration and data according to your retention policy. Ask AWS for the current guidance on deleting Q Business data, because deletion steps can change. The output is a decommission record that names the approver, lists the removed resources, and points to the retained evidence.

Running Onyx alongside Q Business and cutting over safely

Run both systems side by side for a bounded pilot group before any cutover, and define the exit criteria in writing before the pilot starts. Pick a group of users from one or two departments who already use Q Business daily, and give them Onyx with the same connectors scoped to the same sources. Build a fixed set of test questions drawn from real work, including questions whose answers must be blocked for some users. Ask a second group of reviewers to run each question in both tools and record the sources cited, the answer quality, and any document that appears in one tool but not the other. Treat any document visible to a user in Onyx but not in the source application as a blocking defect. Agree on the thresholds with the security and compliance owners, and confirm how Q Business applies its own permissions and how Onyx sync treats groups and deleted files in each connector, since those details differ by source.

Model routing is a separate decision that affects both cost and exposure. Onyx can call Ollama, LiteLLM or vLLM for self-hosted models, or a commercial provider such as OpenAI, Anthropic or Gemini. If you place LiteLLM in front of models, its virtual keys need a PostgreSQL database and carry per-key, per-user and per-team budgets, rate limits and model restrictions. Test that a key cannot reach a model it was not issued for, and that the master key sits in a secret manager, not in configuration files. If you serve models with vLLM, the --api-key option does not cover every endpoint, including /metrics and /health, so place a reverse proxy in front that allowlists only the endpoints users need. Confirm the exact endpoint list against the current vLLM security documentation before go-live, and check that node-to-node traffic in any multi-node deployment sits on an isolated network.

What drives migration cost and duration

This table lists the inputs that move the cost and schedule of a move from Amazon Q Business to Onyx, with the reason each one matters and how to keep it under control. Use it to scope the work before asking for a quote, since the largest effects usually come from permissions, identity and validation rather than from the software itself.

Driver	Why it moves cost or time	How to keep it down
Number of data sources	Each connector needs its own credentials, scope definition, sync schedule and test pass. S3, SharePoint, Confluence and Salesforce each behave differently, and every additional source adds configuration and checks.	Start with the sources that hold the most-used content. Retire stale sources in the inventory before migrating them, and confirm each connector against the Onyx connectors directory.
Permission model complexity	Q Business applies permissions from each source. Nested SharePoint groups, Confluence space restrictions and Salesforce sharing rules must be mirrored so answers draw only on documents users can already see. Complex models take the most testing time.	Document the permission model per source before migration. Ask whether Onyx permission sync covers each source type you use, and test with a sample of users from each group.
Count of Q Apps and guardrails	Q Apps and guardrail rules are rebuilt by hand in Onyx agents and actions. Each app needs its prompts, inputs, outputs and access rules re-specified and tested. Guardrails may need separate policy controls outside Onyx.	Export the Q Apps definitions and rank them by use. Retire unused apps and map guardrails to explicit controls in the written scope so gaps are visible early.
Identity integration	Onyx supports SSO through Google OAuth, OIDC or SAML and SCIM provisioning. Replacing IAM Identity Center mappings, group claims and deprovisioning rules requires coordination with the identity team and a test of offboarding.	Confirm which identity provider holds the group membership used for permissions. Agree the SAML or OIDC attribute mapping and the SCIM behavior for removed users before build starts.
Model hosting choice: GPU capacity	Self-hosted models need GPU capacity sized for expected concurrency, and the hardware and accelerator type drive capital or cloud spend. vLLM runs on several accelerator types, so hardware selection affects the work needed.	Pilot with a hosted model or a smaller model first. Ask for a sizing estimate tied to your query volume and document count, and confirm the accelerator support with the vendor.
Model hosting choice: API usage	Calling proprietary providers such as Anthropic, OpenAI or Gemini bills per token and removes GPU work, but usage recurs with every query. Volume and prompt length determine the monthly bill.	Measure query volume during the pilot. Set spend limits per team or key, and ask for a usage projection in the quote rather than a fixed figure.
Model hosting choice: operations staff	Running model servers, gateways and the Onyx services requires people for patching, upgrades, monitoring and incident response. This recurring effort is often larger than the first build.	Decide who owns each service before go-live. Ask whether an ongoing support retainer is part of the written scope and what it covers.
Validation scope	Answer quality, permission leakage tests and regression checks against Q Business outputs take time. Broader user groups and more sources multiply the test cases.	Agree a fixed set of test questions and expected sources with business owners. Limit the first release to the groups and sources in scope, and record results for each test.
Compliance evidence	Assessors expect records of access controls, change history, audit logs and retention settings for the new assistant. Assembling this evidence is extra work if it was not planned during build.	Ask for evidence collection as a named deliverable. Confirm which query history and audit logs Onyx provides, and agree with your assessor which artifacts they need before testing begins.

How the migration differs by starting point

A small team with one or two data sources and no Q Apps usually has the shortest path. The main work is reconnecting those sources to Onyx, checking that the users who ask questions have the same access they had before, and choosing one model provider. Because there is little custom behavior to rebuild, the inventory step is mostly a confirmation exercise.

Source inventory: List each connected source and its sync scope using the AWS CLI and the Q Business console, then confirm the same files or sites are selected in Onyx's connectors.
Identity: Decide whether Onyx's built-in login or Google OAuth, OIDC or SAML fits your directory, and confirm group membership maps to the people who should see each source.
Model choice: Pick one hosted or self-hosted model provider that Onyx supports and test answer quality on a sample of real questions from your team.
Retired features: Confirm that no one depends on Q Apps or Q guardrails. If nobody does, record that decision rather than rebuilding it.
Operations: Decide who restarts services, applies upgrades and watches disk use, since a small team often has no dedicated platform owner.

Before cutover, ask your implementation partner to show a test user seeing only the documents they could see in Q Business.

What usually goes wrong and how to prevent it

Most failed Amazon Q Business migrations do not fail on the model. They fail on what the assistant can see, who can reach it, and whether anyone can prove what it did. The cards below cover the risks we see most often and the check that prevents each one.

Permissions flattened during re-indexing

Re-indexing a source with a service account, or with a shared index that ignores per-document ACLs, can let staff see answers drawn from folders they could never open in SharePoint or Confluence. Onyx syncs source permissions, so answers draw only on documents the user can already see. Before cutover, pick a set of restricted documents in each source, sign in as users without access, and confirm that no answer quotes them.

Connector coverage gaps at cutover

Q Business data source connectors do not map one-to-one to Onyx connectors, and a source that was indexed in Q may be missing, paused or syncing on a different schedule in Onyx. Build a table from your Q inventory that lists each source, its owner, its sync frequency and the matching Onyx connector. Confirm each connector in the connectors directory before you retire the Q application, and record any source that has no equivalent.

Unvalidated answers at cutover

Users will ask Onyx the questions they asked Q, and differences in chunking, retrieval and the chosen model can change answers that policies or procedures depend on. Build a fixed test set from real questions and expected sources, run it against both systems, and review every answer that cites different documents. Sign off on the set with the business owners before users are moved.

Exposed model or API endpoints

A model server that is reachable beyond the assistant can be called directly, bypassing Onyx's permission checks. The vLLM security guidance states that its --api-key option does not protect every route, including /metrics and /health, and recommends a reverse proxy that allowlists only the endpoints meant for users. Place model servers on a private network, expose only the chat and embedding paths you need, and test the unlisted paths from outside the network.

Q Apps logic lost without a replacement

Q Apps, custom actions and the guardrails configured in Q are easy to overlook because they are not data sources. Each one encodes a business rule, such as which topics are blocked or which workflow runs on a question. Export the Q Apps definitions and guardrail settings, write down the rule each one enforces, and assign a named owner to rebuild it in Onyx agents and actions or in a gateway policy before the Q application is disabled.

No retained audit evidence

Once the Q application is closed, its query history and admin logs may not remain available on the schedule your compliance team needs. Decide which evidence auditors will ask for, such as access logs, query history and connector configuration changes, and export it from Q before shutdown. Then confirm that Onyx query history auditing and your log platform keep the same records for the retention period your policies require.

Questions buyers ask before migrating from Amazon Q Business

How much effort and cost should we expect when moving from Amazon Q Business to Onyx?

The work is paid as implementation effort plus recurring infrastructure and support, and the total depends mostly on how many data sources you reconnect and how much permission logic must be verified. Onyx Community Edition is MIT licensed, so software licensing is not the main line item, but the cost of running it is. One-time costs cover inventory, connector setup, permission testing, model selection and cutover. Recurring costs cover compute for the index, database, model serving (GPU capacity or API usage), backups, upgrades and staff time. Ask for a written scope that separates these components, and compare it against your current Q Business subscription and index unit-hours.

How long does a migration from Amazon Q Business to Onyx take?

The timeline is set by the number of sources, the complexity of their permission models, the model hosting choice and how much change control your organization requires. Connecting a few well-documented sources is a different job from reconnecting many systems with group nesting, shared drives and custom identity mappings. Parallel running with a pilot group usually adds time because results must be compared before cutover. No duration is promised here; request a fixed-scope plan from DeployOpen that lists sources, deliverables and milestones in writing before work starts.

What does the migration need from our internal team?

Your team needs to supply the inventory, access and decisions that only you can provide. In practice this means an owner for each data source, administrator access to the identity provider and to the systems being connected, a clear list of user groups, and sign-off on which content is in scope. Security and compliance staff should review the retention, logging and data residency choices, and someone must own the model and inference decisions. Ask the implementation partner which of these items they expect from you and when, so the schedule does not stall on approvals.

Can our own engineers migrate from Amazon Q Business to Onyx without a partner?

Yes, a capable internal platform team can deploy Onyx, since it documents Docker, Kubernetes, Helm and Terraform paths and an air-gappable setup. The harder parts are the permission sync checks, SSO and SCIM wiring, self-hosted model serving and ongoing upgrades. Teams that do it alone should plan for testing that answers only draw on documents each user can already see in the source application, and for a monitoring and patch routine. Many organizations split the work: internal staff run the platform while an outside party handles the security validation or a defined set of integrations.

How do we make sure permissions carry over from S3, SharePoint and Confluence?

Onyx connects to 50+ applications and syncs their permissions, so an answer should only draw on documents the user can already see in the source system. Migration must still verify this per source, because Q Business permissions came from IAM Identity Center and its own connector configuration, which do not map one to one. Test with sample users from each group, confirm that deny rules and nested groups behave correctly, and check that SCIM provisioning removes access when users leave. Document the test results as evidence for your access reviews and ask the partner to include this verification in the written scope.

What happens to Q Apps and guardrails when we leave Amazon Q Business?

Q Apps and Q Business guardrails do not move automatically, so each one must be rebuilt, replaced or retired. Onyx covers RAG, AI chat, agents and actions in its Community Edition, which can replace many Q Apps workflows, but each app needs its logic re-created and tested. Guardrails must be reviewed as policy: restate the content rules, identify the topics you blocked and decide where enforcement sits, whether in Onyx configuration, the model gateway or the reverse proxy. Inventory every Q App and guardrail before cutover, record its owner and purpose, and confirm the replacement with the people who use it.

How DeployOpen scopes and runs the migration

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, so a move from Amazon Q Business to Onyx is handled as a written, fixed-scope engagement. The work starts with an agreed scope covering data sources, permissions, models and the retired Q Apps and guardrails, then moves through build, testing and handover.

How we scope

Inventory of Amazon Q Business data sources, plugins and index settings, collected with the AWS CLI and agreed in writing
Mapping of each source to an Onyx connector, with a permission sync test plan for SharePoint, Confluence and Salesforce
Decisions on model providers, self-hosted inference and which Q Apps and guardrail behaviors are rebuilt or retired

How we build

Deployment of Onyx in your AWS account or data center using Docker, Kubernetes, Helm or Terraform, as the scope specifies
Configuration of SSO through Google OAuth, OIDC or SAML and SCIM provisioning, checked against your identity provider
Testing that answers only return documents users can already see in each source application, before any user onboarding

How we hand over

Written documentation of the connectors, permission mappings, model configuration, backup routines and upgrade steps
Runbooks for operating the index, database and model servers, with the operating effort your team should expect to carry
Evidence and configuration records prepared for your internal reviews or for an independent assessor, which DeployOpen does not itself certify

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover
Retainer scope, response expectations and upgrade cadence are confirmed in writing before work begins
A quote follows from the written scope, so ask for line items covering each source, model and environment

Migrate from Amazon Q Business to Onyx