litellm - 💡(How to fix) Fix [Feature]: Export UI-managed proxy state to a declarative file

The Feature

Operators running multiple LiteLLM proxy environments (dev / staging / prod, or regional clusters) currently have no first-class way to export the proxy's UI-managed state into a declarative artifact that can be re-applied in another environment.

config.yaml is declarative for everything sourced at startup, but UI- and API-driven state — teams, organizations, virtual keys, credentials, MCP servers, agents, access groups, models added via the dashboard, and a chunk of general_settings (alerting, SMTP, etc., persisted into LiteLLM_Config) — lives only in the database. There is no single endpoint or CLI that emits all of that state in a redeployable form.

Motivation

Multi-environment promotion ("apply what's in staging to prod") is a common operational need, especially for regulated deployments where every config change has to be reviewable and reproducible. Today this requires either:

1. Hand-stitching a backup script across the per-resource admin endpoints (/team/list, /organization/list, /key/list, /credentials, GET /v1/mcp/server, GET /v1/agents, /v2/model/info, plus the access-group endpoints and /config/list / /alerting/settings for general settings). Works, but every team rebuilds it independently and it drifts as new entity types are added.
2. A pg_dump of the LiteLLM tables. Simple and complete, but couples the workflow to the Prisma schema and is hard to review as a diff.

Neither path produces a human-reviewable, re-applicable artifact.

Current state in the codebase

For context on the gap:

• /config/yaml (litellm/proxy/proxy_server.py:14138) is documented as a mock Swagger endpoint and returns {"hello": "world"}.
• /config/list (litellm/proxy/proxy_server.py:13651) returns metadata for a narrow allow-list of general_settings fields only.
• The only yaml.dump in the proxy (litellm/proxy/proxy_server.py:3255) is on the /config/update write path — it serializes the updated in-memory config back to the YAML file when DB persistence is disabled. It does not walk DB-backed state.

The per-entity GET endpoints listed above all exist and return enough information to reconstruct each table; the missing piece is the single-call aggregation and a defined import contract.

Proposed feature

A single admin endpoint (e.g. GET /config/export) — or an equivalent CLI wrapper — that returns a declarative snapshot of UI-managed state in a versioned format (YAML or JSON), re-applicable via a matching POST /config/import endpoint or CLI command.

In scope (entities verified against the current schema):

• Teams, organizations, internal users, team/org memberships
• Virtual keys (with secret handling — see open questions)
• Credentials (LiteLLM_CredentialsTable)
• Models added via the UI (LiteLLM_ProxyModelTable)
• MCP servers, toolsets (LiteLLM_MCPServerTable, LiteLLM_MCPToolsetTable)
• Agents (LiteLLM_AgentsTable)
• Access groups and model access groups
• Guardrails (LiteLLM_GuardrailsTable)
• Tags (LiteLLM_TagTable)
• Budgets (LiteLLM_BudgetTable)
• Object permissions (LiteLLM_ObjectPermissionTable)
• Pass-through endpoints (already a config-table surface)
• DB-persisted general_settings: alerting config, SMTP, cost margin / discount, pass-through endpoint settings, etc.

Explicitly out of scope:

• Spend logs, audit logs, daily-spend aggregations, error logs (operational history, not configuration).
• Master key / salt key material.
• End-user records (LiteLLM_EndUserTable) — these grow unbounded and are closer to operational state than configuration.

Implementation notes (suggestive — not prescriptive)

Some shapes that might be a good approach:

• Aggregate inside the proxy by calling the existing per-resource list helpers, so the export naturally inherits each entity's existing access control and field filtering. Avoids a second source of truth for what counts as "exportable" state.
• Stable, versioned envelope (e.g. schema_version: 1) so imports can detect and reject incompatible snapshots.
• Idempotent import: upsert by stable IDs where they exist (team_id, org_id, key alias, server_id, agent name); deterministic conflict behavior for collisions (skip / replace / merge as an opt-in flag).
• Optional filtering (include=teams,keys,mcp_servers) so operators can promote subsets of state.
• A CLI wrapper (litellm config export / litellm config import) that drives the same endpoints, for use from CI/CD pipelines.

Open questions

• Secret material. Credentials, MCP server credentials, virtual key hashes, SMTP passwords, etc., are sensitive. Two reasonable shapes: (a) the export emits them in encrypted form (using LITELLM_SALT_KEY) and the target environment must share the same salt to import; or (b) the export emits redacted placeholders and import requires a separate re-bind step. Option (b) is friendlier across environments with different salt material but adds an extra step. Either could be a good approach depending on how the team thinks about cross-environment key parity.
• general_settings scope. Some general_settings fields are deployment-specific (e.g. database_url, host/port, master key) and shouldn't be exported. The current /alerting/settings and /config/list allow-lists give a useful starting point for what's safe to round-trip, but it would be worth being explicit about which keys are in scope.
• Pass-through endpoints and prompts. These are first-class entities today but live in less-trafficked surfaces; flagging them so they're not forgotten in any first cut.

Related

• #18428 — "LiteLLM Operator for deeper integration with Kubernetes and GitOps" — complementary direction (a Kubernetes Operator + CRDs that reconcile FROM declarative manifests INTO LiteLLM). A native export endpoint would also make a Operator-side reverse-sync ("what's in the cluster that isn't in Git?") tractable.

What part of LiteLLM is this about?

Proxy