Open Kortyx on GitHub

Deploy Kortyx Studio on a Server

Updated 17 minutes ago • August 2, 2026

This guide is the portable starting point for a VM, ECS, Cloud Run, Kubernetes, or infrastructure as code. It runs Studio and the telemetry API with an external PostgreSQL database.

It does not install TLS, a reverse proxy, PostgreSQL, or a cloud secret manager for you.

For a laptop: Use Run Studio Locally. Do not turn the CLI-managed local Compose state into an internet-facing installation.

Prerequisites

  • Docker Engine with Docker Compose v2, or an equivalent container platform;
  • PostgreSQL reachable from the telemetry API and database job;
  • a pinned Kortyx Studio release tag; and
  • HTTPS plus an access boundary before remote exposure.

Read Credentials and Secrets before provisioning values.

1. Prepare the deployment

Download these files from the same immutable Kortyx release:

Create a private directory and copy the environment template:

compose_file=/path/to/compose.external-postgres.yml deployment_dir=/path/to/private/kortyx-studio mkdir -m 700 "$deployment_dir" cp /path/to/external-postgres.env.example "$deployment_dir/deployment.env" chmod 600 "$deployment_dir/deployment.env"

Generate a fresh, unpersisted credential set:

npx kortyx studio credentials --generate

Put those values directly into your secret manager, or into deployment.env for a controlled single-server installation. Set DATABASE_URL and replace vX.Y.Z with an immutable published release.

For a network database, follow the provider's TLS requirements. With a publicly trusted certificate, a typical PostgreSQL URL ends in ?sslmode=verify-full. Percent-encode reserved characters in database usernames and passwords.

2. Start the services

docker compose \ --env-file "$deployment_dir/deployment.env" \ -f "$compose_file" \ up -d --wait --wait-timeout 180

Compose runs the retryable migration/bootstrap job before starting the API and Studio.

The default host bindings are loopback-only:

  • Studio: http://127.0.0.1:6300
  • Telemetry API: http://127.0.0.1:6400

Keep loopback bindings when a reverse proxy runs on the same server. On a container platform, route service traffic directly to container ports 6300 and 6400 rather than assigning both services unrestricted public addresses.

3. Verify health

curl --fail http://127.0.0.1:6400/health docker compose \ --env-file "$deployment_dir/deployment.env" \ -f "$compose_file" \ ps docker compose \ --env-file "$deployment_dir/deployment.env" \ -f "$compose_file" \ logs --tail 200

A Studio health response below 500 is healthy; 401 is expected when Basic Auth protects the route.

4. Put access controls in front

Before users or SDK producers connect:

  • terminate HTTPS at a trusted load balancer or reverse proxy;
  • keep PostgreSQL private;
  • restrict the telemetry API to application-server networks when possible;
  • keep Studio and the API on a private service network; and
  • use Basic Auth only over HTTPS, ideally behind a VPN or identity-aware proxy.

Basic Auth is not encryption. It is only acceptable over HTTPS. Never expose a remote Studio instance over plain HTTP.

5. Connect SDK producers

Give the SDK application's server runtime only the telemetry connection values:

server environment
KORTYX_TELEMETRY_API_URL=https://telemetry.example.com KORTYX_TELEMETRY_API_KEY=ktyx_live_... KORTYX_TELEMETRY_ENVIRONMENT=production KORTYX_TELEMETRY_SERVICE_NAME=my-agent

The application server must reach the telemetry endpoint. The key must never enter a browser bundle. Continue with Connect Your Project.

Upgrade

  1. Back up PostgreSQL and deployment secrets.
  2. Change KORTYX_STUDIO_IMAGE_TAG to the next supported release.
  3. Pull the images.
  4. Run the database job and wait for success.
  5. Recreate the API and Studio services.
docker compose --env-file "$deployment_dir/deployment.env" -f "$compose_file" pull docker compose --env-file "$deployment_dir/deployment.env" -f "$compose_file" run --rm db-init docker compose --env-file "$deployment_dir/deployment.env" -f "$compose_file" up -d --wait api studio

Database downgrade is unsupported. Restore a backup made for the older release if its schema is incompatible.

Translate the contract to a cloud platform

Infrastructure tooling should represent the same components rather than run Compose verbatim:

  1. one retryable job using the API image and kortyx-studio-db migrate-and-bootstrap;
  2. one long-running telemetry API service;
  3. one long-running Studio service; and
  4. one externally managed PostgreSQL database.

Reference secret-manager entries from workload definitions. Do not serialize raw secret values into Terraform state, generated manifests, or CDK source.

Use the Configuration Reference to map ports, variables, health checks, startup order, and service responsibilities to your platform.