Bring Your Own AI Provider

Archyl includes AI features for architecture discovery, ADR parsing, chat, insights and managed agents. By default, all of these run on a model managed by Archyl. Organizations that have an existing AI provider relationship — for compliance, contractual or data-residency reasons — can route every AI request through their own provider with their own credentials.

When BYO Provider is enabled:

• Every AI feature is routed through the provider you configure
• Archyl quota enforcement (chat queries, AI discovery, agent runs) is skipped — your provider invoices you directly for token usage
• Per-feature model selection lets you mix models (e.g. Claude Sonnet for chat, Claude Opus for discovery)

This is an organization-level setting; only organization admins can configure it.

Supported providers

The OpenAI-compatible adapter is a single configuration that covers a long tail of vendors. You provide a base URL and an API key, and Archyl talks to the endpoint as if it were OpenAI.

Configuration

Step 1 — Open the AI tab

Go to Organization Settings → AI. The tab is only visible to admins.

Step 2 — Pick a provider

Select one of the five provider cards. Each card has its own credential requirements:

• OpenAI / Anthropic / Google — API key only
• OpenAI-compatible — API key + base URL (e.g. https://api.openrouter.ai/api/v1, https://api.mistral.ai/v1, https://models.github.ai/inference)
• AWS Bedrock — credentials in the form <access_key_id>:<secret_access_key> (with optional :<session_token> suffix for STS credentials), plus an AWS region (e.g. us-east-1)

Step 3 — Configure per-feature models (optional)

Each AI feature can use a different model. Leave any field blank to fall back to the provider's default.

Use the exact model identifier as published by the provider (claude-opus-4-5, gpt-4o, mistral-large-latest, anthropic.claude-sonnet-4-20250514-v1:0, etc.). Archyl passes it straight through.

Step 4 — Test the connection

Click Test connection. Archyl issues a minimal completion against the configured provider with your credentials. A green checkmark confirms the credentials work; an error surfaces the provider's response so you can fix the configuration before saving.

Step 5 — Enable and save

Tick Enable BYO provider for this organization and click Save settings. The next AI request from anyone in the organization — chat, discovery, agent run, ADR import — will be routed through your provider.

Quota behaviour

When BYO Provider is disabled (the default), AI usage counts against your subscription's monthly quota:

• AI discovery operations
• Chat queries
• Managed agent runs

When BYO Provider is enabled, all three quotas are bypassed for the organization. You pay your provider directly for tokens used; Archyl no longer rate-limits these features. Your seat-based subscription still applies for everything else (collaboration features, team limits, etc.).

The bypass takes effect immediately when you enable the toggle and reverses immediately when you disable it.

Security

API keys are encrypted at rest using AES-256-GCM with the platform's encryption key. They are never returned in API responses — once stored, the UI displays •••••••• along with a "key is stored" indicator, and the key is only decrypted in-process when an AI request needs to be made.

To replace an existing key, type the new value and save. To clear it entirely, click Remove configuration, which deletes the row and reverts the organization to the platform-managed AI.

Only organization admins can read or modify these settings. Members continue to use AI features transparently — the routing is invisible to them.

Managed agents

When BYO Provider is enabled, managed agent runs execute entirely on your provider, with your credentials. Archyl's own model is never used as a fallback.

If the provider cannot run agents, or no model is set for an OpenAI-compatible endpoint, starting a run fails with an explicit message instead of running on a model you did not choose.

Troubleshooting

"Test connection" fails with 401 / 403. Re-check that the key is pasted correctly with no surrounding whitespace. For Bedrock, make sure the format is <access_key_id>:<secret_access_key> (colon-separated) and the region matches a region where the model has been enabled in your AWS account.

"baseUrl is required for openai_compatible provider". The base URL field is mandatory for the OpenAI-compatible adapter. It should point at the root of the API, e.g. https://api.openrouter.ai/api/v1 — without /chat/completions at the end.

Discovery returns invalid JSON. Archyl's prompts are tuned for OpenAI's strict JSON mode. Some providers/models return JSON inside markdown code fences or add commentary. Switch to a model with strong JSON-mode reliability (e.g. gpt-4o, claude-sonnet-4-6, gemini-2.0-flash) for the Discovery, Structure analysis and Relationship refinement features specifically — chat and other features are more permissive.

Chat works but discovery fails on Bedrock. Some Bedrock model IDs require Provisioned Throughput or specific cross-region inference profiles. Check the model is enabled for your account in the Bedrock console and that the region you picked matches the model's availability.

Related features

• AI-Powered Discovery — uses your configured provider when BYO is enabled
• Managed Agent Runs — run on your Anthropic, Bedrock, OpenAI or OpenAI-compatible provider