# Deploy Claude apps gateway

> Claude Code: Private networking, OIDC, Kubernetes, Cloud Run, GCP, Postgres, health checks, upgrades and cache forwarding.

URL: https://docs.passion8.cc/en/docs/claude-code/gateway-cloud-deployment
Language: en
Publisher: Passion8

Apps gateway ships in the claude binary. It authenticates users through enterprise IdP and forwards Code requests to Anthropic, Bedrock, Google Agent Platform, Foundry or AWS Platform, adding SSO, settings, limits and telemetry.




The official login endpoint must use private or controlled networking. Public internet addresses fail login safety checks because the gateway can distribute command-executing policies.




## When to use it

| Option | Suitable for | Unsuitable for |
| --- | --- | --- |
| Apps gateway | SSO, groups, managed settings, limits, OTLP and multiple providers | Unattended CI without browser login |
| Passion8/custom gateway | Existing routing, model pools and billing | Official apps-gateway IdP/managed features |
| Direct provider | Small teams, CI, simple keys/IAM | Central budgets, audit and per-user attribution |

Setting only the URL may still use locally stored claude.ai credentials. Explicit gateway tokens or gateway login place billing behind the gateway's provider account.

## Deployment steps

| Stage | Action | Acceptance |
| --- | --- | --- |
| IdP | Confidential OIDC app with /oauth/callback | Discovery, email and group/role claims work |
| Container | Pinned Linux binary | Verified manifest, nonroot user and writable config directory |
| Platform | Kubernetes, Cloud Run or own platform | Health, readiness and OAuth metadata work |
| Policy | forceLoginMethod and forceLoginGatewayUrl | Gateway login option appears |
| Operations | Logs, database, limits, upgrades and secrets | Audit/OTLP, backups and rollback runbook |

Terminate TLS at the front proxy, use HTTP to replicas, and configure public_url/trusted_proxies for callbacks, per-IP limits and audit addresses.

## OIDC considerations

| IdP | Check |
| --- | --- |
| Okta | Organization authorization server may need userinfo_fallback for email/groups |
| Entra ID | Groups are often object IDs; app roles can use the roles claim |
| Google Workspace | ID tokens omit groups; use Directory API or email-domain policy |
| Keycloak/Dex | Discovery, authorization-code flow and refresh tokens |

Without refresh tokens, longer session.ttl_hours reduces login frequency but delays revoked-user convergence.

## Kubernetes operations

```yaml title="Deployment outline"
containers:
  - name: claude-gateway
    image: registry.example.com/claude-gateway:2.1.x
    command: ["claude", "gateway", "--config", "/etc/claude/gateway.yaml"]
    readinessProbe:
      httpGet:
        path: /readyz
        port: 8080
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
```

Recommendations:

- Mount configuration through ConfigMap or read-only secret volumes.
- Store OIDC/JWT secrets, database URL and upstream keys in a secret manager.
- Use workload identity, not long-lived cloud keys in images.
- Add ingress/internal-load-balancer addresses to trusted_proxies.
- Decide whether database failure should remove every replica from readiness.

## Google Cloud topology

Official examples use Cloud Run or GKE, private-IP Cloud SQL, Secret Manager and Vertex Agent Platform upstreams.

| Component | Cloud Run | GKE |
| --- | --- | --- |
| Runtime | Cloud Run service,min instances 1 | GKE Deployment |
| Network | Internal/cloud-load-balancing ingress and private DNS/LB | Internal ingress and proxy-only subnet |
| Database | Private-IP PostgreSQL | Private-IP PostgreSQL |
| Identity | Agent Platform service account | Workload Identity |
| Secrets | Secret Manager env / file mount | Secret Manager CSI driver |

Default run.app hosts resolve publicly. Use an internal application load balancer or Private Service Connect/private DNS for production login.

## Operations and upgrades

| Item | Handling |
| --- | --- |
| Logs | Audit events and gateway operational logs on stderr |
| Health | healthz checks process; readyz also checks storage |
| Postgres | Grants, rates, spend, audit and principal emails |
| JWT rotation | Add new secret first; remove old after TTL |
| Upgrade | New binary migrates schema; stateless replicas roll |
| Rollback | Migrations append, but older binaries reject unknown configuration |

With spend limits, Postgres stores budget state as well as login state. Plan backups, retention and outage policy.

## Cache and protocol forwarding

| Check | Why it matters |
| --- | --- |
| Unbuffered SSE | Incremental tools and responses rely on streaming |
| Preserve beta headers | Search, context and one-hour features depend on them |
| Preserve system arrays | Order matters for attribution and cache keys |
| Preserve tools/cache_control | Required by MCP, deferred tools and cache |
| Preserve usage cache tokens | Needed for read/write analysis |

One-hour TTL requires client, gateway and upstream support. Otherwise document a five-minute fallback and mark it in telemetry.

## Official references

- [Run Claude Code through a gateway](https://code.claude.com/docs/en/gateways.md)
- [Claude apps gateway deployment and operations](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md)
- [Deploy Claude apps gateway on Google Cloud](https://code.claude.com/docs/en/claude-apps-gateway-on-gcp.md)
- [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway.md)
- [Gateway protocol reference](https://code.claude.com/docs/en/llm-gateway-protocol.md)

## Related pages



- [Gateway protocols](https://docs.passion8.cc/en/docs/claude-code/gateway): Endpoints, forwarding, discovery, attribution and errors.
- [Gateway operations](https://docs.passion8.cc/en/docs/claude-code/gateway-operations): OIDC, database, budgets, discovery and settings boundaries.
- [Enterprise deployment](https://docs.passion8.cc/en/docs/claude-code/enterprise-deployment-overview): Provider, identity, policy, permissions and observability decisions.
- [Monitoring](https://docs.passion8.cc/en/docs/claude-code/monitoring): OTel, analytics, traceparent, privacy and gateway boundaries.