Provisioned Resources

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 two private storage buckets used for hosting customer specific artifacts: gs://cartesia-{name} (production) and gs://dev-cartesia-{name} (dev).

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 Buckets

Two customer-specific buckets host voice migrations etc that your self-hosted deployment consumes at runtime:

gs://cartesia-{name} — production artifacts
gs://dev-cartesia-{name} — dev artifacts, for testing voices and pronunciation dictionaries before adding them to production

Both buckets share the same layout:

gs://cartesia-{name}/
  migrations/
    v2/
      migrations/         # voice and pronunciation-dictionary migration files

The API server syncs from migrations/v2/migrations/. Files land in migrations/v2/migrations/ when you call POST /onprem/add-voices or POST /onprem/add-pdict against the Cartesia cloud API. Pass dev_bucket: true to either endpoint to target the dev bucket. 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 method	Config file	Documentation
Kubernetes (Terraform — AWS EKS)	`aws-terraform.tfvars.example`	Managed Kubernetes
Kubernetes (Terraform — GCP GKE)	`gcp-terraform.tfvars.example`	Managed 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.example`	Docker

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 Name	Description
`cartesia-api`	API server
`cartesia-license-proxy`	License validation and enforcement
`cartesia-sonic-azure-disco`	TTS worker — sonic-3.5
`cartesia-sonic-rosy-dragon`	TTS worker — sonic-3
`cartesia-sonic-royal-plant`	TTS worker — sonic-2
`cartesia-sonic-voice-clone`	TTS 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.

Overview

Deployments

Guides

Performance

Service Account

Customer Artifact Buckets

Deployment Configurations

Configuration Files

Container Registry

Images

Listing Available Tags

Mirroring to a Private Registry

​Service Account

​Customer Artifact Buckets

​Deployment Configurations

​Configuration Files

​Container Registry

​Images

​Listing Available Tags

​Mirroring to a Private Registry

Service Account

Customer Artifact Buckets

Deployment Configurations

Configuration Files

Container Registry

Images

Listing Available Tags

Mirroring to a Private Registry