Isolation mode

The Isolation mode screen lets you read and set the isolation mode of the tenant or of one project: connected, local_only or air_gapped. When the mode is not connected, the gateway refuses every external route and every outbound call to a host that is not local or declared internal. Portal path: /llm/isolation. It is used by tenant administrators and security officers. The screen is built in portal/src/screens/kit-data.tsx (Isolation, isolationCfg).

What the screen shows

• The section Current mode ("Leave the project empty for the tenant mode."): the field Project with Apply, then the effective mode as a badge (neutral for connected, warning otherwise) and the JSON {"project_id", "mode", "internal_hosts"} read from GET /v1/llm/isolation. The effective mode is the row of the project when it exists, else the row of the tenant, else connected.
• The panel Set the isolation mode ("Applies to the tenant or to one project."): the fields Mode (connected, local_only, air_gapped, required), Project (empty: the tenant) and Internal hosts (comma separated, for example <vllm-host>, <ollama-host>), the button Run and the JSON Result.

In local_only and air_gapped, a model is routable only when its provider is a local engine (vllm, ollama, lm_studio) or when its address is one of the Internal hosts; the egress barrier also lets through 127.0.0.1, localhost and the operator services such as the LiteLLM proxy.

Actions

Button or action	What it does	API call	Roles
Apply (Current mode)	Reads the effective mode of the project typed, or of the tenant when empty.	GET /v1/llm/isolation	tenant_admin, platform_admin, security_officer, finops, developer, auditor, viewer
Run (Set the isolation mode)	After the confirmation "Set the isolation mode? This sensitive action is recorded in the audit log.", writes the mode and the internal hosts of the tenant or of the project.	PUT /v1/llm/isolation	portal: tenant_admin, security_officer; server: tenant_admin, platform_admin, security_officer

Roles

• Reading GET /v1/llm/isolation: the READ roles of services/control-plane/src/eai/domains/llm/lifecycle.py: tenant_admin, platform_admin, security_officer, finops, developer, auditor, viewer.
• Writing PUT /v1/llm/isolation: ADMIN plus security_officer in the same file (tenant_admin, platform_admin, security_officer). The portal shows the form to ROLES.isolationWriters of portal/src/lib/kit.ts (tenant_admin, security_officer); other roles see "Requires one of these roles".
• Every change is recorded in the audit log (llm.isolation.set). The routes need a tenant (tenant_required otherwise).

Typical tasks

Put a project in local only mode

1. Read the current mode. Type the project in Project and click Apply, so that you know where you start from. Expected result: the badge shows the effective mode, connected when nothing is set. If it fails: an error panel with Retry gives the cause.
2. Declare the internal hosts. In Set the isolation mode, choose Mode local_only, type the same Project, and list the Internal hosts that serve local models (host or host:port, for example <vllm-host>:8000). Expected result: the form is valid. If it fails: Required under Mode.
3. Apply the mode. Click Run and confirm. Expected result: the Result shows the mode and the sorted, lowercase hosts. If it fails: "Parameter internal_hosts is invalid." means a host has a wrong format.
4. Check the effect. Call an external model from the Gateway playground with this project. Expected result: "Mode local_only: model <model_id> of provider <provider> is external and cannot be routed." If it fails: the model may be local or served by an internal host, which is allowed.

Return to connected mode

1. Set the mode. In Set the isolation mode, choose Mode connected, type the Project (or leave it empty for the tenant) and click Run, then confirm. Expected result: the Result shows connected. If it fails: "Requires one of these roles" means your role cannot change the mode.
2. Read it again. Click Apply in Current mode. Expected result: the badge shows connected. If it fails: a project row overrides the tenant row; set the project itself.

Troubleshooting

Symptom	Cause	Fix
"Parameter mode is invalid." (parameter_invalid, 422)	Mode outside connected, local_only, air_gapped.	Choose one of the three values.
"Parameter internal_hosts is invalid." (parameter_invalid, 422)	A host contains a scheme, a path or characters outside letters, digits, dot and dash: the format is host or host:port.	Type only the host name and the optional port.
"Mode <mode>: model <model_id> of provider <provider> is external and cannot be routed." (isolation_external_route, 403) at call time	The mode refuses external providers.	Use a local model, add its host to Internal hosts, or return to connected.
"Mode <mode>: outbound call to <host> refused, only local and internal endpoints are allowed." (isolation_egress_denied, 403)	The outbound address of the model is not internal.	Add the host to Internal hosts.
"This operation needs a tenant context." (tenant_required, 400)	No tenant.	Sign in on a tenant.
The tenant mode is set but a project stays connected	The project has its own row.	Set the mode of the project as well.

Related pages

• Gateway playground
• Providers
• Router and fallbacks
• Local inference (B-02)
• Local GPU management (B-13)