Deployment Model Spec

Status: Canonical Implements: Core Principles Principle 11 (Open by default, sovereign by design) Authority for: Deployment modes, self-hosting requirements, local model integration, air-gapped configuration, open-source component inventory

Overview link

Synedrix OS supports three canonical deployment modes. All modes run the same platform code, the same agent architecture, and the same governance model. The deployment mode affects only one dimension of the platform: where model inference occurs and whether external API calls are permitted. Who operates the data plane is a separate, independent declaration (§1.1).

This document defines the three modes, their requirements, and the constraints each imposes. It is the authoritative reference for infrastructure decisions and the enforcement companion to Core Principles Principle 11.

1. The three deployment modes link

What runs where in each mode:

flowchart LR
    HK["Inbound Hookdeck Event Gateway: managed external service, required in all modes"]
    subgraph m1["Mode 1: Cloud-connected"]
        P1["12 platform components, self-hosted except the inbound Hookdeck Event Gateway"]
        I1["Inference: external cloud APIs"]
        P1 -->|"outbound HTTPS"| I1
    end
    subgraph m2["Mode 2: Self-hosted hybrid"]
        P2["12 platform components, self-hosted except the inbound Hookdeck Event Gateway, plus local model inference layer: Ollama or vLLM"]
        I2["Agents whose model_type is cloud, declared or inherited from the business instance default: external APIs"]
        L2["Agents whose model_type is local: local models"]
        P2 -->|"selective outbound HTTPS"| I2
        P2 --> L2
    end
    subgraph m3["Mode 3: Air-gapped"]
        P3["11 of the 12 platform components plus local model inference layer"]
        L3["Local models only: no outbound connection"]
        P3 --> L3
    end
    HK -->|"inbound events"| P1
    HK -->|"inbound events"| P2
    HK -->|"inbound delivery only"| P3

Mode 1 — Cloud-connected link

Definition: All Synedrix OS platform components run self-hosted on the customer’s own infrastructure. Model inference uses external cloud APIs. No business data is stored on external infrastructure — data flows to model APIs for inference only.

What runs locally: All 12 platform components (n8n, LangGraph, Hookdeck, Hookdeck Outpost, Redis, Supabase, QuestDB, Neo4j, Qdrant, Langfuse, PostHog, Grafana + Prometheus), with the Hookdeck Event Gateway as the one managed external service (§2).

What uses external services: Model inference API calls (OpenAI, Anthropic, Google, or others). Langfuse and PostHog cloud versions may be used as alternatives to self-hosted, if the customer accepts their data processing terms.

External network requirements: Outbound HTTPS to model provider APIs. Optional: outbound to Langfuse/PostHog cloud if not self-hosting those components.

Suitable for: organisations comfortable with standard cloud data processing agreements; development and staging environments; organisations without strict data residency requirements.

Not suitable for: organisations with data sovereignty requirements prohibiting inference data leaving their infrastructure; regulated industries where business data cannot flow to external APIs; air-gapped environments.

Mode 2 — Self-hosted hybrid link

Definition: All Synedrix OS platform components run self-hosted-hybrid. Model inference is split at the agent level: some agents use external cloud APIs, others use local models via Ollama or vLLM. The split is declared per agent in the runtime policy.

What runs locally: All 12 platform components plus the local model inference layer (Ollama or vLLM).

What uses external services: Only the agents explicitly configured with model_type: cloud in their runtime policy. All other agents are fully local.

External network requirements: Selective outbound HTTPS to model provider APIs for cloud-configured agents only. All other traffic is internal.

Suitable for: organisations that require local inference for sensitive, high-risk, or regulated workflows while accepting cloud APIs for lower-sensitivity tasks; organisations managing infrastructure cost by using local models for high-volume low-sensitivity tasks and cloud models for complex reasoning tasks.

Configuration requirement: Each agent runtime policy must declare model_type: cloud | local. Agents without a declared model_type inherit from the business instance default.

Mode 3 — Air-gapped (fully local) link

Definition: All Synedrix OS platform components run self-hosted, with one accepted exception: the inbound Hookdeck Event Gateway (§2). All model inference uses local models. No outbound connection or external API call of any kind originates from the customer’s infrastructure, and no business data leaves it. Inbound event payloads from external sources are held in transit by Hookdeck before delivery; this is the only third-party custody of data in Mode 3.

What runs locally: All platform components except the inbound Hookdeck Event Gateway (that is 11 of the 12, including LangGraph) plus the local model inference layer (Ollama for standard workloads, vLLM for high-throughput production).

What uses external services: Exactly one — the inbound Hookdeck Event Gateway (Layer 8), a proprietary managed cloud service with no self-hosted option. It is required in all modes: ADR-OS-013 considered replacing it with an open self-hosted Event Receiver and rejected that, accepting the exception instead. No other external service is permitted.

External network requirements: Outbound: none — network egress rules should be configured to block all outbound traffic from platform components. This is a network-level enforcement, not a platform-level assumption. Inbound: delivery from the Hookdeck Event Gateway to the Layer 8 ingress destination, and nothing else. This is a deliberate opening in the perimeter and must be disclosed to, and accepted by, the customer before the instance is declared air-gapped.

Suitable for: regulated industries (Finance, Healthcare, Legal, Government, Insurance); classified or defence environments; organisations with strong data sovereignty requirements — provided their policy tolerates the single inbound Hookdeck path above.

Not suitable for: environments that forbid any third-party transit or custody of inbound payloads, or any inbound connection from an external service. Synedrix OS currently provides no self-hosted ingress substitute for them; a Hookdeck Enterprise arrangement is a commercial option that would have to be established directly with the vendor. Do not describe Mode 3 as “zero external connections” or “no data ever leaves or enters the perimeter” in sales, documentation or content.

Platform invariant: A business instance declared as deployment_mode: air-gapped cannot contain any agent runtime policy with a cloud model URI in primary_model or fallback_model. This is a validation error enforced at business instance configuration time.

1.1 Hosting variants: who operates the data plane link

The mode says where inference runs and what external calls are permitted. It does not say who operates the platform components. ADR-OS-008 splits the platform into a pooled control plane and a per-tenant data plane (n8n, LangGraph, Redis, Qdrant, Neo4j, QuestDB and the observability stack), and admits two hosting variants of the data plane:

Who operates the data plane, independent of the mode:

flowchart LR
    CP["Pooled control plane"]
    CL["Control plane run locally as a single tenant"]
    subgraph self["Self-operated: Modes 1, 2 and 3"]
        D1["Data plane on the customer's own infrastructure"]
    end
    subgraph managed["Managed: Modes 1 and 2 only"]
        D2["Data plane operated by Synedrix, dedicated to one tenant and never pooled"]
    end
    D2 -->|"initiates authenticated connection"| CP
    D1 -.->|"may run the control plane locally as a single tenant"| CL

Rules for the managed variant:

• A managed data plane is never pooled: it serves one tenant, in every mode. Operating it for the customer does not make it shared.
• The mode keeps its meaning. A managed Mode 1 or Mode 2 instance has the same model-inference and external-call rules as its self-operated counterpart, and the same agent runtime policy validation.
• The business instance declares which variant it uses. The declaration is hosting configuration owned by the business instance, in the same way as the mode declaration (§6). Its field name and schema belong to the Tenancy Spec that ADR-OS-008 calls for.
• The managed variant is a convenience, not a capability gate. Every capability a managed data plane provides is available self-operated, from the same canonical implementation, so a tenant can move between variants.
• “Runs on the customer’s own infrastructure” in the mode definitions above describes the self-operated variant. For the managed variant it is read as infrastructure dedicated to the tenant and operated on its behalf.
• A managed data plane initiates its authenticated connection to the pooled control plane, as the ADR requires. A self-operated instance may instead run the control plane locally as a single tenant.

Mode 3 is self-operated only in this version. A Synedrix-operated data plane would give a third party operational access to an environment whose definition forbids third-party handling beyond the single inbound Hookdeck path, and the ADR leaves it open whether that can be reconciled. Until a separate decision is recorded, Mode 3 is not offered as managed. An air-gapped instance runs its control plane locally as a single tenant and makes no outbound connection to a pooled one.

2. Open-source component inventory link

Every component in the Synedrix OS stack is open source, except Hookdeck (the inbound Event Gateway), which is a proprietary managed cloud service with no self-hosted deployment. Every other component requires no proprietary licence for standard production use. The Hookdeck exception is accepted and recorded in ADR-OS-013; its consequence for Mode 3 is stated in §1. The following table is the authoritative inventory; see the Hookdeck platform reference for the full analysis.

3. Local model inference — configuration reference link

Ollama link

Ollama is the primary local inference tool. It runs as a local server and exposes an OpenAI-compatible API, which means all Langfuse tracing, evaluation, and cost/latency tracking integrations work without modification.

Installation: curl -fsSL https://ollama.com/install.sh | sh (Linux/macOS) or via Docker.

Default endpoint: http://localhost:11434

OpenAI-compatible endpoint: http://localhost:11434/v1

Model management link

ollama pull llama3.1:8b          # Pull a model
ollama list                       # List available models
ollama run llama3.1:8b            # Run interactively

Runtime policy configuration link

primary_model: ollama/llama3.1:8b
model_type: local
local_model_provider: ollama
local_model_endpoint: http://localhost:11434

GPU support: Ollama auto-detects NVIDIA (CUDA) and AMD (ROCm) GPUs. Falls back to CPU if no GPU is available. CPU inference is functional but slower — suitable for development; GPU recommended for production.

vLLM link

vLLM is recommended for high-throughput air-gapped production deployments requiring concurrent inference across multiple agents.

Requirement: NVIDIA CUDA GPU (recommended: A100, H100, or equivalent). AMD ROCm experimental.

Default endpoint: http://localhost:8000

OpenAI-compatible endpoint: http://localhost:8000/v1

Runtime policy configuration (vLLM) link

primary_model: vllm/meta-llama/Llama-3.1-8B-Instruct
model_type: local
local_model_provider: vllm
local_model_endpoint: http://localhost:8000

Langfuse tracing with local models link

Langfuse traces local model inference using the OpenAI SDK integration pointed at the local endpoint. No code changes are required — only the OPENAI_BASE_URL environment variable needs to point to the Ollama or vLLM endpoint.

Token cost attribution is not applicable for local inference. In air-gapped deployments, set compute_cost_tracking: true in the agent runtime policy to track GPU compute time instead.

4. Recommended local models by use case link

Model selection is business-instance configuration — the OS does not prescribe specific models. The following recommendations are guidance only.

Quantisation guidance link

• Development: Q4_K_M quantisation (good balance of quality and speed on CPU/low VRAM GPU)
• Production (GPU): Q8_0 or F16 for maximum quality; Q4_K_M for cost-optimised GPU workloads
• Production (high-throughput): vLLM with bfloat16 on A100/H100 class GPU

5. Air-gapped deployment checklist link

Before declaring a business instance as deployment_mode: air-gapped, confirm all of the following:

Infrastructure link

• All platform components are deployed locally and reachable within the network — except the Hookdeck Event Gateway, which has no self-hosted deployment (§2) and is the accepted exception (ADR-OS-013). Confirm the customer has accepted Hookdeck’s transit of inbound event payloads and the inbound delivery path described in §1, and that no other external connection exists
• Ollama or vLLM is deployed and serving at the configured local endpoint
• Required local models are pulled and available (no internet access assumed at runtime)
• Langfuse is deployed locally (self-hosted) — no external telemetry
• PostHog is deployed locally (self-hosted) — no external analytics
• Network egress rules block all outbound traffic from platform components

Configuration link

• Business instance declares deployment_mode: air-gapped
• All agent runtime policies declare model_type: local
• All primary_model and fallback_model values use local URIs (ollama/<model> or vllm/<model>)
• No cloud API keys are present in any agent runtime policy or environment configuration
• cost_budget_usd is set to null or omitted in all runtime policies; compute_cost_tracking: true where applicable

Validation link

• Business instance configuration passes OS validation (no cloud URIs in air-gapped instance)
• All agent runtime policies pass schema validation
• A test invocation of each agent type confirms local inference is responding
• Langfuse is receiving traces from the local model endpoint
• No external DNS resolution is required at runtime

Ongoing link

• Model update process is defined (models must be pulled manually or via internal distribution in air-gapped environments)
• Platform component update process is defined (Docker image updates via internal registry)

6. Deployment mode and the responsibility matrix link

Deployment mode is a business instance concern. The OS owns the validation rules; the business instance owns the declaration and the infrastructure.

7. Invariants link

• All three deployment modes are first-class. No mode reduces platform capability relative to another.
• An air-gapped business instance must not contain cloud model URIs in any agent runtime policy. This is a platform validation error, not a warning.
• Model selection is always business-instance configuration. The OS defines the integration interface, not the model.
• All platform components in this spec are open source, except Hookdeck, a required proprietary managed cloud service (§2). This is an accepted, standing exception, recorded in ADR-OS-013, not an open item. It makes Hookdeck the one declared external dependency of Mode 3 (§1); no other external dependency is permitted in an air-gapped instance.
• A data plane is never pooled across tenants, whichever party operates it. The managed variant is available only in Modes 1 and 2; Mode 3 is self-operated until a separate decision records otherwise.
• Local model version tags must be pinned in production deployments to prevent silent changes on server update.
• Air-gapped deployments must plan model and component updates through internal distribution — no runtime internet access should be assumed or required.

Versioning link

• Version: 0.4
• Supersedes: v0.3
• Implements: Core Principles v0.3 Principle 11
• Related: Synedrix OS - Platform Architecture & Tech Stack, Synedrix OS - Agent Runtime Policy Spec, Synedrix OS - Responsibility Matrix, Synedrix OS - Core Principles

Related Documents link

Core Principles and Canonical Reference link

• Synedrix OS - Core Principles — Principle 11 (Open by default, sovereign by design) is the governing constraint that this document implements.
• Synedrix OS - Consolidated Canonical Reference — Consolidated synthesis; §9 summarizes the three deployment modes defined here.

Architecture link

• Synedrix OS - Responsibility Matrix — Capability-by-capability ownership split; includes deployment-mode rows that reference this spec.
• Synedrix OS - Platform Architecture & Tech Stack — 12-platform stack; specifies all open-source components and their self-hosting requirements per deployment mode.

Agent Runtime link

• Synedrix OS - Agent Runtime Policy Spec — Runtime policy schema; the deployment_mode field and local model routing implement this spec at the agent layer.

Vocabulary link

• Synedrix OS — Vocabulary — Canonical glossary; deployment sovereignty addendum defines deployment mode, air-gapped deployment, self-hosted instance, Ollama, vLLM.

Synedrix OS · August 2026