Deploy Yukta for a team

Use this when you move Yukta from your laptop to a machine other people or other systems call. For a first install on a laptop, start with Install Yukta. Prerequisites: you know which install method fits (the table below), and you can run a reverse proxy that ends TLS, such as nginx or Caddy.

Yukta is in alpha. The release server and the Docker image are the Community edition: they keep sessions and run history in memory. Storing state on disk, PostgreSQL, high availability and remote workers need a build you make yourself. See Persist sessions before you promise anyone that a restart keeps their workflows.

Pick how to install it

Method	Platforms	Choose it when
Docker image `ghcr.io/infenia/yukta`	Linux, and macOS or Windows through Docker Desktop (`linux/amd64`; `linux/arm64` from `0.1.0-alpha.4`)	You already run containers. The image holds the native server and nothing else
`.deb` or `.rpm` package	Linux `amd64` (`arm64` from `0.1.0-alpha.4`)	You want a `systemd` service, a service user and a settings file
Install script (`install.sh`)	Linux and macOS; with `0.1.0-alpha.3` and earlier only Linux `amd64` gets the server	You want the binaries in `/usr/local/bin` with checked checksums
Archive (`.tar.gz`, `.zip` on Windows)	Linux, macOS and Windows, from `0.1.0-alpha.4` (`0.1.0-alpha.3` and earlier: Linux `amd64`)	You manage the service yourself
From source	Anything with JDK 25	You need a Plus build, extra plugins or a custom plugin. See Write a plugin

Steps

Make a key for the first administrator

A server that listens on anything but loopback refuses to start without an API key. Make a long random one now and keep it in your secret store:

export YUKTA_KEY="$(openssl rand -hex 32)"

The server warns about a key shorter than 32 characters. To keep the plain key off the server, give it the SHA-256 digest instead, written sha256:<64 hex digits>; clients still send the plain key. See Secure the server.

Start the server

Docker
Linux package
Install script
Archive
From source

The image listens on 0.0.0.0 inside the container, so it always needs a key. Publish the port on loopback and let the reverse proxy in step 3 face the network:

docker run -d --name yukta --restart unless-stopped \
  -p 127.0.0.1:9858:9858 \
  -e YUKTA_API_KEYS_0_NAME=admin \
  -e YUKTA_API_KEYS_0_KEY="$YUKTA_KEY" \
  -e YUKTA_API_KEYS_0_ROLE=ADMIN \
  ghcr.io/infenia/yukta:0.1.0-alpha.4

The image has no shell and no curl. It runs as the unprivileged user 65532.

Install the .deb or .rpm from the release page. The package adds a yukta user and a systemd unit, and leaves the service stopped. Put the address and the key in /etc/yukta/yukta.env:

sudo tee -a /etc/yukta/yukta.env >/dev/null <<EOF
YUKTA_API_KEYS_0_NAME=admin
YUKTA_API_KEYS_0_KEY=$YUKTA_KEY
YUKTA_API_KEYS_0_ROLE=ADMIN
EOF
sudo systemctl enable --now yukta

Leave YUKTA_SERVER_ADDRESS unset so the server stays on 127.0.0.1 behind the proxy. The package sets the file to mode 0640, so other users cannot read the key. Follow the logs with journalctl -u yukta -f.

curl -fsSL https://github.com/infenia/yukta/releases/download/v0.1.0-alpha.4/install.sh | sh

This puts yukta and yukta-cli in /usr/local/bin (as root) or ~/.local/bin, after checking their checksums. It starts nothing. Run the server under a service manager of your choice, with the same three YUKTA_API_KEYS_0_* variables:

YUKTA_API_KEYS_0_NAME=admin YUKTA_API_KEYS_0_KEY="$YUKTA_KEY" YUKTA_API_KEYS_0_ROLE=ADMIN yukta

Unpack the .tar.gz from the release page. It holds the native yukta server and yukta-cli. Run yukta as in the install-script tab, under your own service manager.

./gradlew :boot:bootJar
YUKTA_API_KEYS_0_NAME=admin YUKTA_API_KEYS_0_KEY="$YUKTA_KEY" YUKTA_API_KEYS_0_ROLE=ADMIN \
  java -jar boot/build/libs/boot-*.jar

A jar started with no flags runs the prod profile. ./gradlew bootRun runs dev instead, which logs more and is for development only. For a native binary, ./gradlew :boot:nativeCompile needs GraalVM 25.

Check the server on the host

curl -fsS http://127.0.0.1:9858/actuator/health
curl -fsS -H "Authorization: Bearer $YUKTA_KEY" http://127.0.0.1:9858/api/me

The first call returns {"status":"UP"} and needs no key. The second shows the name and role of your key.

Put TLS in front of it

Yukta serves plain HTTP, and keys travel in request headers, so end TLS in a reverse proxy on the same host. Two things matter in the proxy: do not buffer event streams, and do not close idle ones early (the server sends a keep-alive comment every 15 seconds).

nginx
Caddy

server {
  listen 443 ssl;
  server_name yukta.example.com;
  # ssl_certificate and ssl_certificate_key go here

  location / {
    proxy_pass http://127.0.0.1:9858;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_buffering off;
    proxy_read_timeout 1h;
  }
}

yukta.example.com {
  reverse_proxy 127.0.0.1:9858 {
    flush_interval -1
  }
}

These are examples; adapt them to your proxy. When you set a key, the Host and Origin check that protects a keyless local server is off, so no extra setting is needed for the host name. The one-time-token answer path (/api/inputs/token-answer) rate-limits by caller address; for that to be the caller and not the proxy, set server.forward-headers-strategy=framework and make the proxy replace X-Forwarded-For as shown.

Tell clients where the server is

export YUKTA_SERVER_URL=https://yukta.example.com
export YUKTA_TOKEN="$YUKTA_KEY"
yukta-cli whoami

For named keys with limited roles per person or agent, see Secure the server. Do not hand the first administrator key to every client.

Give it time to stop

On a stop signal the server refuses new starts and gives running runs yukta.execution.shutdown-timeout (30 seconds by default) to finish. The packaged systemd unit waits 45 seconds. In an orchestrator, set the stop grace period above 30 seconds. Use GET /actuator/health as the probe: the image has no shell for an exec probe.

Verify it worked

From another machine:

curl -fsS https://yukta.example.com/actuator/health
curl -s -o /dev/null -w '%{http_code}\n' https://yukta.example.com/api/sessions
curl -fsS -H "Authorization: Bearer $YUKTA_KEY" https://yukta.example.com/api/me

The health call returns {"status":"UP"}. The second call prints 401, because it sent no key. The third returns your key’s name and role. If the container or service exits at start, read its log: “Refusing to listen on … without an API key” means no key reached the server. See Troubleshoot.

Variations that matter

Choose the plugins you ship. Optional plugins are chosen when you build, with -Pyukta.plugins=default, all, none or a comma-separated list. A running server cannot add or remove them. The settings and the plugin names are in Configuration reference and the plugin reference.
Run more than one server. Failover needs a Plus build and PostgreSQL. See Run highly available.
Install on a machine with no internet. Copy a release’s files to a web server laid out as <base>/vX.Y.Z/<file>, then run install.sh with YUKTA_DOWNLOAD_BASE=<base>. Read the script first if you need to audit it.
Check a download. Every release publishes SHA256SUMS and a Sigstore signature for it. See Releases.
Publish the API description. The prod profile serves no Swagger UI or /v3/api-docs. To turn them on behind your key, see Secure the server.

Install Yukta: the first install, on a laptop
Upgrade and roll back
Secure the server
Configuration reference: every setting, its default and its environment variable
How durability and high availability work

Build workflows

Work with AI

Supervise runs

Run and operate

Extend

Deploy Yukta for a team

Pick how to install it

Steps

Verify it worked

Variations that matter

Pick how to install it

Steps

Verify it worked

Variations that matter

Related