Deployment patterns

APAI distinguishes install modes by where the install lands, not by whether the LLM is allowed to install. LLMs install software all the time when they have shell access. The honest distinction is about storage ownership and persistence.

local-tool

Default for developers and CI environments. The agent has shell access and can execute the underlying installer (npm, pip, brew, cargo, gh skill, gemini extensions, claude connectors, the APAI registry). APAI wraps that install with a Capability Passport, scanner output, and a durable receipt.

cloud-sandbox

Use when working in a hosted chat surface (ChatGPT, Claude.ai, Gemini, Grok). The agent applies the package protocol inside the session-scoped sandbox. Capability Passport is read in-context, but no durable receipt persists outside the session. Tell users this explicitly - they must record install state themselves if they need audit trail.

remote-connector

Use when the agent needs a tool surface without local install: Claude.ai custom connectors, xAI Grok remote MCP, ChatGPT Apps SDK. The user adds a URL pointing at a remote MCP server. Nothing is fetched to the user's machine; the agent gains the tool via the MCP protocol. APAI catalogs public connectors with their Passports.

Personal local-first

Individual developer, no Gateway. Ollama or LM Studio for local models. APAI CLI manages installs. All state on the developer's machine. Free tier. Privacy maximal.

Team with Gateway

Small team or startup. APAI Gateway deployed on shared infra (Docker Compose or single-node Kubernetes). RBAC via the Gateway. Shared approved package catalog. Audit logs ship to a SIEM. Pro/Team tier.

# Pseudocode - real manifests land with Phase 4
docker run -d \
  -p 8080:8080 \
  -e APAI_AUTH_PROVIDER=oauth \
  -e APAI_DATABASE_URL=postgres://... \
  -e APAI_AUDIT_LOG_PATH=/var/log/apai/audit.jsonl \
  apai/gateway:latest

Enterprise air-gapped

Regulated industry or air-gapped environment. APAI Gateway deployed in a VPC or fully air-gapped network. Private registry hosts internal-only packages. SSO via Okta / Entra ID / SAML. Compliance-ready audit trail exported to SIEM. SLSA-style provenance chain on every install (Phase 4 with real signing keys).

For scalable production deployments, run the APAI Gateway in Kubernetes with horizontal pod autoscaling, secrets management via Vault or Kubernetes Secrets, and OpenTelemetry export to your observability stack.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: apai-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: apai-gateway
  template:
    metadata:
      labels:
        app: apai-gateway
    spec:
      containers:
      - name: gateway
        image: apai/gateway:0.1
        ports:
        - containerPort: 8080
        env:
        - name: APAI_AUTH_PROVIDER
          value: oidc
        - name: APAI_OIDC_ISSUER
          value: https://your-idp.example.com
        - name: APAI_DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: apai-secrets
              key: database-url
        resources:
          requests: { cpu: 100m, memory: 256Mi }
          limits:   { cpu: 1000m, memory: 1Gi }

Route Gateway traces to your observability platform of choice. See observability docs for the integration patterns (Langfuse, LangSmith, Arize Phoenix, Helicone, generic OpenTelemetry).