> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Deployment Hardening

> Harden AIvis production deployments with network, secret, storage, logging, and backup controls.

AIvis can run in different deployment forms. The hardening checklist below applies to production environments regardless of whether services run on one host, multiple hosts, or managed infrastructure.

## Network exposure

| Service                                                     | Recommended exposure                                                                    |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Nginx or request router                                     | Public, protected by TLS and deployment firewall rules.                                 |
| AIvis Web and API                                           | Private behind the router unless your deployment has a specific internal access design. |
| Agent Runtime and Tool Bridge                               | Private internal network only.                                                          |
| Postgres, Redis, OpenSearch, MinIO or S3-compatible storage | Private network only.                                                                   |
| Model servers and background workers                        | Private network only.                                                                   |

## Baseline hardening matrix

| Area        | Minimum production control                                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| TLS         | Terminate or forward TLS at the public router. Redirect cleartext traffic or block it entirely.                                          |
| Firewall    | Allow inbound public traffic only to the router. Restrict database, cache, search, model, worker, and runtime ports to private networks. |
| Identity    | Use a reviewed administrator list and remove unused accounts before launch.                                                              |
| Secrets     | Store secrets outside source control and rotate them after incident response, personnel changes, or environment cloning.                 |
| Data stores | Enable durable volumes, backups, encryption where supported, and restore tests.                                                          |
| Logs        | Centralize logs and make them searchable by service, request ID, user, connector, Agent, and job ID.                                     |
| Egress      | Restrict outbound traffic to approved model providers, SaaS APIs, object storage endpoints, and internal services.                       |

## Secrets

* Use deployment secret stores or environment-specific secret management instead of committing secrets to source control.
* Rotate model, connector, service, and object-storage credentials on a documented schedule.
* Use placeholders in runbooks and examples; never paste real authorization tokens, API keys, private keys, or user emails into public documentation.
* Separate credentials by environment so staging access cannot reach production data.

## Credential rotation events

Rotate affected credentials when:

* A connector owner changes.
* A model provider key is copied into a test environment.
* A runtime or bridge service is redeployed with changed access policy.
* An administrator leaves the operating team.
* Logs, screenshots, tickets, or chat messages accidentally include a secret.

## Storage and backup

Postgres, OpenSearch, and object storage contain the most important durable state. Production deployments should define backup cadence, retention, restore testing, encryption at rest, and disaster recovery ownership before broad user rollout.

| Store          | Backup focus                                                                          |
| -------------- | ------------------------------------------------------------------------------------- |
| Postgres       | Users, sessions, configuration, credentials metadata, connector state, and job state. |
| OpenSearch     | Searchable document content, vector data, and retrieval indexes.                      |
| Object storage | Uploaded files, connector objects, and documents required to rebuild indexes.         |
| Configuration  | Environment variables, service definitions, routing rules, and secret references.     |

## Logging and monitoring

Log request IDs, service health, indexing jobs, connector sync failures, runtime errors, and authorization denials. Avoid logging raw secrets, full credential payloads, or unrestricted user content unless your deployment policy explicitly requires it.

Monitor at least:

* API error rate, latency, and authorization denials.
* Connector sync status, skipped documents, and credential failures.
* Indexing queue depth and model-server latency.
* Agent runtime failures, tool denials, and long-running jobs.
* OpenSearch disk usage, Redis availability, object-storage errors, and Postgres connections.

## Egress control

Connector workers and runtime services may need outbound access to approved SaaS APIs, model providers, or internal services. Restrict egress to the domains and networks required by enabled connectors, integrations, and model providers.

## Incident response preparation

Prepare an operator runbook before production launch:

| Event                         | First actions                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Credential exposure           | Revoke the credential, rotate dependent services, search logs for use, and update affected connector or model configuration.          |
| Over-broad connector indexing | Disable the connector, remove or restrict the document set, rebuild affected indexes if needed, and review group access.              |
| Runtime tool misuse           | Disable the tool or Agent, inspect run logs by request ID, rotate related credentials, and add a regression test for the denied path. |
| Search data inconsistency     | Pause affected ingestion, inspect worker and OpenSearch health, and rebuild the impacted index scope.                                 |

## Production checklist

* Public traffic enters through TLS-protected routing only.
* Internal service ports are blocked from the public internet.
* Administrator accounts and identity provider settings are reviewed.
* Backups have been restored in a test environment.
* Secret rotation and incident response ownership are assigned.
* Logs are searchable without exposing sensitive values.
* Connector scopes and Agent tool scopes are reviewed by a data owner.
* A rollback path exists for model, connector, Agent, and runtime configuration changes.