Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt

Use this file to discover all available pages before exploring further.

When your enterprise contract is finalized, Cartesia provisions the following resources for your account. All provisioned resources are available for download from the on-prem portal.
The on-prem portal is only accessible under the organization that has on-prem enabled. If you don’t see it, switch to that organization in the account switcher.

​
Service Account

A service account is created for your account, this service account has the following accesses:
  • Access to a private artifact registry, which is used to host cartesia provided container images.
  • Access to a common storage bucket: gs://cartesia-onprem containing the deployment configurations.
  • Access to a private storage bucket: gs://cartesia-{{name}} used for hosting customer specific artifacts.
Download the JSON key for this service account from the on-prem portal. Activate the service account before accessing resources hosted on GCloud: 
gcloud auth activate-service-account --key-file=/path/to/service-account.json
gsutil ls gs://cartesia-onprem/  # Verify access

​
Customer Artifact Bucket

The customer-specific bucket gs://cartesia-{name} hosts voice migrations and LoRA checkpoints that your self-hosted deployment consumes at runtime: 
gs://cartesia-{name}/
  migrations/
    v2/
      migrations/         # voice and pronunciation-dictionary migration files
  loras/                  # LoRA checkpoints for cloned voices
The API server syncs from migrations/v2/migrations/. Workers sync LoRA checkpoints from loras/. Files land in migrations/v2/migrations/ when you call POST /onprem/add-voices or POST /onprem/add-pdict against the Cartesia cloud API. See Managing Artifacts for the migration APIs and hot-reload behavior.

​
Deployment Configurations

The cartesia-onprem bucket contains versioned repository cartesia-kube which holds all of our deployment configurations. 
gs://cartesia-onprem/
  cartesia-kube/
    latest/
      cartesia-kube-latest.tar.gz   # Latest release archive
      VERSION                        # Current version string
    releases/
      <version>/
        SHA256SUMS                   # Checksums for verification
Download and verify the latest release: 
BUCKET="cartesia-onprem"

gsutil cp gs://${BUCKET}/cartesia-kube/latest/cartesia-kube-latest.tar.gz .
gsutil cp gs://${BUCKET}/cartesia-kube/latest/VERSION .

LATEST_VERSION=$(cat VERSION)
gsutil cp gs://${BUCKET}/cartesia-kube/releases/${LATEST_VERSION}/SHA256SUMS .

mv cartesia-kube-latest.tar.gz cartesia-kube-${LATEST_VERSION}.tar.gz

sha256sum -c SHA256SUMS  # macOS: shasum -a 256 -c SHA256SUMS
tar -xzf cartesia-kube-${LATEST_VERSION}.tar.gz
Once extracted, cartesia-kube contains everything needed for all deployment methods: 
cartesia-kube/
  benchmarking/          # Load testing and benchmarking tools
  cartesia/              # Helm chart + Docker Compose configs
    scripts/
      swarm/             # Docker Swarm deploy scripts
    templates/           # Kubernetes resource templates
      autoscaler/
      resources/
      services/
  infra/                 # Terraform configs
    aws/
      cartesia-eks/      # EKS deployment
    gcp/
      cartesia-gke/      # GKE deployment

​
Configuration Files

Each deployment method has its own configuration file inside cartesia-kube. Copy the .example file, fill in your values, and reference it during deployment.
Deployment methodConfig fileDocumentation
Kubernetes (Terraform — AWS EKS)aws-terraform.tfvars.exampleManaged Kubernetes
Kubernetes (Terraform — GCP GKE)gcp-terraform.tfvars.exampleManaged Kubernetes
Kubernetes (Helm-only, existing cluster)cartesia/values.yaml (full reference) and cartesia/sample-values.yaml (curated example)Managed Kubernetes
Docker Compose / Swarm (beta)local/.env.exampleDocker

​
Container Registry

Images are hosted at us-docker.pkg.dev/cartesia-external/self-serve and tagged with a release tag (e.g. sonic-20251118). The full image reference format is: 
us-docker.pkg.dev/cartesia-external/self-serve/<image-name>:<release-tag>

​
Images

Image NameDescription
cartesia-apiAPI server
cartesia-license-proxyLicense validation and enforcement
cartesia-sonic-azure-discoTTS worker — sonic-3.5
cartesia-sonic-rosy-dragonTTS worker — sonic-3
cartesia-sonic-royal-plantTTS worker — sonic-2
cartesia-sonic-voice-cloneTTS worker — voice cloning
NATS uses a public image and does not need to be pulled from the Cartesia registry.

​
Listing Available Tags

List available image tags sorted by most recent: 
gcloud artifacts docker images list \
  us-docker.pkg.dev/cartesia-external/self-serve/cartesia-api \
  --include-tags \
  --sort-by="~UPDATE_TIME"
Replace cartesia-sonic-api with any image name from the table above. The ~ prefix sorts in descending order, showing the latest tags first.

​
Mirroring to a Private Registry

For air-gapped or network-restricted environments, mirror images to your own registry before deployment. Authenticate Docker with the service account: 
cat /path/to/service-account.json | \
  docker login -u _json_key --password-stdin https://us-docker.pkg.dev
Pull, retag, and push each image. For example: 
CARTESIA_REGISTRY="us-docker.pkg.dev/cartesia-external/self-serve"
PRIVATE_REGISTRY="your-registry.example.com/cartesia"
RELEASE_TAG="sonic-20251118"
IMAGE="cartesia-api"

docker pull ${CARTESIA_REGISTRY}/${IMAGE}:${RELEASE_TAG}
docker tag  ${CARTESIA_REGISTRY}/${IMAGE}:${RELEASE_TAG} ${PRIVATE_REGISTRY}/${IMAGE}:${RELEASE_TAG}
docker push ${PRIVATE_REGISTRY}/${IMAGE}:${RELEASE_TAG}
Repeat for each image in the table above. Then set infra.imageRegistry (Helm) to your private registry URL.