How to route between local models and approved cloud APIs

Routing decides where each model request runs: on the device that made it, on another approved machine running Aventail^™ Link, or with an approved cloud provider through your own account. The useful pattern is simple. Write hard rules first, add preferences second, confirm the policy has reached the device, then send a harmless request and check where it actually ran. A local address alone does not prove a request stayed local.

Short answer

• Aventail^™ Link runs supported models and applies routing policy on each device. Aventail^™ Control distributes policies, models and provider keys ahead of time and receives device and routing events. Control is not a hop in the request path.

• A rule has a condition, a primary destination and up to three fallback hops. The first matching enabled rule wins; otherwise the default route applies.

• Destinations are On device, a network peer, or an approved provider connection. Routing to peers and hosted destinations is currently in beta.

• If the policy permits no destination, the request fails with an error and is not sent anywhere forbidden. Fallback only applies when a permitted destination fails, and only to hops the policy already allows.

How routing decisions are made

Link evaluates requests inside the runtime on the device. It considers the policy delivered to that device, the models available to it, device state and the signals each rule uses. Control is where administrators edit that policy. Because configuration arrives in advance, a request does not wait for Control, and the hosted Control service does not receive prompt or response bodies. A provider you route to still receives the requests sent to it.

Think in two layers.

• Constraints decide which destinations are allowed at all for a workflow: for example, local and internal machines only for confidential work, or no paid API for a particular team.

• Preferences choose among the allowed destinations: for example, prefer the local model, and use an approved provider only when the local destination fails.

Write the constraints first. A preference can never widen what a constraint forbids. If the policy permits no destination for a request, the right outcome is an error the user can see, not quiet routing elsewhere. If permitted destinations exist but are operationally unavailable, only the fallback hops you configured are tried, and the request can still fail.

Destinations and what makes them eligible

On device. The request runs on the device that made it, and Link chooses the local model. The model has to be installed and serving, and suitable for the request.

Network peer. Another approved, reachable machine running Aventail Link. A peer must offer the exact model selected in the rule, and that device must have Serve other devices enabled. Peers can be primary destinations only; they are not fallback hops. This lets you use a stronger internal server for suitable work without treating it as a silent backup.

Provider connection. An approved cloud provider called directly through your organisation's own account, using a key stored in Control's API key vault. The rule selects the provider model. Requests sent there leave your infrastructure and may incur charges under your provider terms. A successful key test proves the key works; it does not test your routing rule.

None of these destinations implies universal compatibility. Check that the model supports what the app needs, such as context length, tool or function calling, structured outputs and streaming, and test answer quality on real tasks with harmless data.

Conditions, primary routes and fallback hops

In Control, routing lives under Fleet operations → Routing. You assign devices to a policy, usually by tag, then build ordered rules. Each rule has:

• a condition the device or request must meet;

• a primary destination;

• up to three fallback hops, tried in order.

The first matching enabled rule wins. Requests that match no rule follow the ELSE default route.

Fallback is triggered by failures: an error or timeout, an authentication failure, a provider outage or an unavailable destination. A slow response alone does not trigger fallback. If you want performance to change the route, use a suitable condition so a different primary destination is chosen in the first place. If every destination in a chain fails, the chain is retried with backoff, and the request can still fail. Fallback is never a guarantee.

Two different situations are easy to confuse:

• No permitted destination. The applicable policy allows no destination for this request. It returns an error and nothing is dispatched to a forbidden destination. Do not fix this by adding a destination the boundary forbids.

• Operational failure. A permitted destination was chosen but is unavailable or fails, for example because its model has stopped. Only configured, permitted fallback hops are tried; if they fail too, the request fails. A stopped model is not, by itself, a policy denial.

The routing documentation shows each field with screenshots.

A fictional example

Illustration only: not a customer deployment, production policy syntax or automatic content detection. Imagine a fictional legal operations team with laptops running Link and one internal server running Link with a larger model. Device tags decide which policy a device receives; they do not classify documents or sensitivity, so the team keeps two separate test profiles.

• Confidential profile: laptops tagged legal-confidential receive a policy whose primary destination is the internal server as a network peer. The server offers the exact selected model and has Serve other devices enabled. There is no provider connection and no external fallback, and there is no automatic switch to the laptop's own model, because peers are not fallback hops. If the server is unavailable, the request fails.

• Public drafting profile: laptops tagged legal-public receive a different policy with On device as primary and one fallback hop to an approved provider connection on the firm's own account. People use these devices only for public or non-sensitive material.

Verify delivery, then the real destination

A saved rule is not yet a working route. Check in this order.

1. Delivery. In the Routing table, wait for the device's Delivery state to show applied. Delivering means the policy is still on its way; Unconfirmed means the revision was not confirmed, so check the device's agent version and connection first. An offline device's old route is not evidence it can serve requests now.

2. Effective route. The Route column shows the destination and the policy, rule or default responsible. Signal shows the reported condition behind the decision.

3. Real request. Send a small, harmless request using a model ID returned by the device's /v1/models endpoint, following Connect your software, then confirm the observed destination in Recent usage.

Keep two tests apart:

• Restricted test: synthetic data only, on an isolated test device whose policy is local-only, with no peer, no provider connection, no fallback and no other inherited routes. Briefly stop local serving and confirm the request fails rather than escaping elsewhere. If a restricted policy permits a peer, the peer may validly serve the request, so stopping the local model need not produce an error. Stopping a model also does not prove a no-permitted-destination case; that depends on the policy the administrator applies. Never add an external fallback to make this test pass, and restore serving and the original policy afterwards.

• Local-first test: public text only, on the policy with a cloud fallback. Send one request with local serving running, then briefly stop local serving and confirm the provider handled the retry. Restore local serving afterwards.

Testing what actually happens matters because "A local API address does not guarantee local processing when a cloud route or fallback is configured," as the routing docs put it.

Where Aventail^™ Connect fits

Aventail^™ Connect is how supported apps enter this routing. With a model serving, ticking an app such as Claude Code or OpenCode under Connected Apps in Link connects it automatically. Connect is part of Link, not another hop: the app's model requests reach Link, the model is chosen in Link, and the same policy decides where each request may run. The app's other network activity still follows its own settings. Step-by-step: the Claude Code setup guide and the OpenCode setup guide.

Data, storage and cost boundaries

Routing governs where model requests run. It does not, by itself, govern everything an app stores or sends. Review conversation and document storage, analytics, logs, connectors and each app's own telemetry separately.

For cost, decide which teams and workflows may use paid APIs, and keep provider-side spending limits on the provider account. Local execution avoids external token fees but still has hardware, energy and platform costs.

Change safely

Before you change a live policy, record the current policy and its revision. Apply the change to one tagged test device, confirm delivery and the observed destination, then roll out in stages using fleet configuration. If acceptance checks fail, restore the previous approved policy and confirm devices show it as applied. Agree in advance who approves routing changes and who owns recovery. Managing policies and provider keys requires the Fleet Admin or Super Admin role.

FAQ

Can a peer act as a backup if the local model fails?

No. Peers are primary destinations only. Use a fallback hop to another allowed destination, or accept an error.

Will a slow local model switch to the cloud automatically?

Not by fallback. Slowness alone does not trigger fallback; use a condition if performance should choose the primary route.

Does Aventail^™ see our prompts when routing?

Link makes the decision on the device. The hosted Control service receives device and routing events, not prompts or responses. Any provider you route to receives the requests sent to it.

What happens when nothing is allowed?

The request returns an error and is not sent to a forbidden destination. Treat that as the boundary working, then review the policy deliberately.

Next steps

• Read how routing works and how Aventail^™ Enterprise manages devices and policy together.

• For sensitive workflows, use the validation checks in keeping sensitive AI requests within approved infrastructure.

• For the wider decision about providers and self-hosted models, read how to reduce AI provider dependency.

• Check compatibility and versions and the architecture and data flow docs.