Manage a local Studio installation

Updated 3 hours ago • October 18, 2026

These commands manage Docker containers on your machine. They do not operate a Cloud installation or log in to a remote server. For prerequisites and the complete first-run path, follow Run Studio locally.

Local state is stored in ~/.kortyx/studio by default. Supply the same --home on later commands when using another directory.

Everyday commands

Command	Purpose	Preserves data?
`npx kortyx studio start`	Create or update the stack and wait until healthy	Yes
`npx kortyx studio status`	Show container state and local endpoints	Yes
`npx kortyx studio logs`	Follow API, Studio, bootstrap, and database logs	Yes
`npx kortyx studio logs --no-follow`	Print recent logs and return	Yes
`npx kortyx studio credentials`	Print the current local connection details	Yes
`npx kortyx studio credentials --format dotenv --service-name my-agent`	Print copyable server-side SDK variables	Yes
`npx kortyx studio restart`	Recreate the stack and wait until healthy	Yes
`npx kortyx studio stop`	Stop the containers	Yes

Good to know: Start is idempotent. Running it again is the normal way to bring back a stopped installation or apply a changed image tag or port configuration.

Preserve active evaluations

The table's data-preservation column describes stored data. It does not promise that an in-flight evaluation survives stop, restart, a changed image, credential rotation, or reset. If evaluations are configured, prepare worker retirement while the consumer still accepts later cases, and wait for durable Studio results before replacing Studio services. If the consumer application is also being replaced, drain it after Studio saves those results.

These CLI commands do not coordinate worker and consumer retirement. The built-in updater refuses configured evaluation targets; keep automatic updates paused and use controlled maintenance. A fixed Compose stop timeout can force-kill long work. Direct stop/reset remains operator teardown, and older images lack the new drain hooks. Check the first-upgrade procedure before using the new signals.

Start options

Choose different host ports:

Pin both Studio images to an immutable published release:

Studio image tags use the Studio release version, not the CLI package version. CLI and Studio minor versions may differ while remaining compatible through the stable Studio API protocol. studio status reports the configured image and the negotiated protocol; studio inspect rejects only an incompatible protocol major or a response that violates the advertised protocol.

Use an alternate state directory or local username:

The same --home value must be supplied to later commands. Alternatively, set KORTYX_STUDIO_HOME for the shell or automation that manages that installation.

Print or rotate local credentials

Print the current browser and SDK connection values:

Print only the server-side SDK variables for an application:

This format intentionally omits the browser password and local state path, but it still includes a secret telemetry write key. Keep the output server-side.

Replace the browser password and both application API-key secrets:

Rotation updates the local environment atomically, applies new key verifiers, recreates affected services, and attempts rollback if the application fails. The previous telemetry key becomes invalid, so update and restart every local SDK producer.

The database password and API-key pepper are deliberately preserved.

Generate credentials for remote deployment

This produces an unpersisted credential set without creating local Studio state. Store it immediately in the deployment's secret manager. It cannot be printed again later.

See Credentials and Secrets before using generated values on a server.

Reset local data

Destructive command: Reset permanently deletes the local PostgreSQL volume. It preserves generated credentials, so the next studio start creates an empty database and bootstraps those keys again.

Back up any telemetry you need before resetting. See Operations and Troubleshooting.

Good to know: A normal stop or restart preserves data. Before a destructive reset, make a backup and keep the matching credentials and pepper.

Local CLI versus remote operation

Lifecycle commands manage the local Compose stack; read commands query the Studio HTTP API. Read commands cannot execute/resume runs, approve interrupts, publish topology, or administer remote projects. The CLI does not SSH into servers, edit a remote database, or replace your cloud platform's deployment tools.

For remote environments, use Deploy on a Server, inject secrets through the platform, and operate the same container contract through your infrastructure tooling.

Next: Back up or restore local data.