korta.Get started ↗
DOCS / INSTALLATION

Install Korta

Korta has two parts. The core korta CLI runs Markdown roles from your own machine over SSH. Korta Enterprise adds a self-hosted manager, web console, API, vault and team workflows. The CLI can also connect to that manager.

Requirements

To build from source, install Git and the Go version required by each repository's go.mod, currently Go 1.26 or later. Install an OpenSSH client on the machine running the CLI or manager. Managed hosts need SSH access with root or passwordless sudo. Check the supported host operating systems before choosing a host.

Install the core CLI

The quickest option is a release archive. Download the archive for your system from the core releases page, check its checksum, and put korta on your PATH:

VERSION=0.1.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')          # linux or darwin
ARCH=$(uname -m)
case $ARCH in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
FILE=korta_${VERSION}_${OS}_${ARCH}.tar.gz

curl -fsSLO "https://github.com/nexusrun/korta/releases/download/v$VERSION/$FILE"
curl -fsSLO "https://github.com/nexusrun/korta/releases/download/v$VERSION/checksums.txt"
grep " $FILE\$" checksums.txt | shasum -a 256 -c -    # prints: OK

tar -xzf "$FILE"
sudo install -m 755 "korta_${VERSION}_${OS}_${ARCH}/korta" /usr/local/bin/korta
korta version

With Go 1.26 or later, go install github.com/nexusrun/korta/cmd/korta@latest puts korta in $(go env GOPATH)/bin.

To build from source, clone the core repository and run make build, which writes bin/korta:

git clone https://github.com/nexusrun/korta.git
cd korta
make build
./bin/korta --help

Release archives cover Linux and macOS on amd64 and arm64, and Windows on amd64 and arm64. The Windows builds work with the Enterprise manager; to run roles over SSH from Windows, use WSL. The CLI runs roles without a manager.

Run your first role

Create hosts.md with a reachable test host:

# Staging
- web1 ubuntu@10.0.0.5 env=staging

Create role.md:

# Packages
- nginx, curl

# Services
- nginx started, enabled

Then preview and apply:

korta inventory -i hosts.md
korta plan role.md -i hosts.md --limit env=staging
korta apply role.md -i hosts.md --limit env=staging

The plan changes nothing. The apply command plans again, asks for confirmation, then applies. SSH uses your existing configuration, keys, agent and known_hosts by default. See the CLI guide for identity overrides, CI, and approvals.

Build and start the Enterprise manager

With access to the Enterprise repository, build and start the manager:

git clone git@github.com:nexusrun/korta-enterprise.git
cd korta-enterprise
make build
./bin/korta-server

By default, the manager listens on 127.0.0.1:8080 and stores state under ./data. Open http://127.0.0.1:8080 on that machine and use the administrator token in data/admin-token to sign in. Create an owner account under Access for normal use and keep the administrator token for emergencies. See the Enterprise guide for access grants, data storage, and configuration.

For remote access, put the manager behind a TLS reverse proxy that sets X-Forwarded-Proto: https. Back up the state and vault key together. If KORTA_DATABASE_URL selects PostgreSQL, provide KORTA_VAULT_KEY and KORTA_ADMIN_TOKEN through the manager environment. Review the upgrade guide before upgrading.

Sign the CLI into the manager using a personal API token, or the administrator token for initial setup:

korta login --server http://127.0.0.1:8080 --token-file ~/.korta-token
korta instances list

A release image is also built for Linux amd64 and arm64. Follow the Enterprise release instructions for the image available to your installation. The image includes OpenSSH, listens on port 8080 and uses /data for file-based state; persist that directory when using file storage.

Next steps

BUILT WITH KORTAAll documentation ↗