Install kageos

Run kageos locally with Podman Desktop, or deploy a Linux production server with one command. The installer prints your system login on first install.

Prerequisites

macOS or Windows: install Podman Desktop and complete the Podman machine onboarding
Linux production server: sudo access, public IP or domain, and enough disk for images and data
Desktop Podman machine: 6 GB RAM and 20 GB disk recommended; Linux production: 4 GB minimum, 8 GB recommended
Local desktop installs use port 8080 by default; production installs normally use port 80/443

Choose Platform

macOS and Windows are for local trials. Linux is the production deployment path.

Local trial

Run kageos locally on macOS

Use this when you want to try kageos on your Mac before setting up a Linux server.

View install.sh Download Podman Desktop

Install and run

Install Podman Desktop, finish Podman machine onboarding, then run kageos.

 $   brew install --cask podman-desktop 
 $   curl -fsSL https://kageos.com/install.sh | bash -s -- --port 8080 

What this path does

Open Podman Desktop and complete Podman machine onboarding before running the kageos installer.
Creates a persistent kageos-data volume and runs the qiayanai/kageos image.
The installer prints the system login after the first successful install.

After install

Open

http://localhost:8080

Use this URL on the same machine after the installer finishes.

Username

system

The built-in admin account created on first boot.

Password

kageos password

The installer prints it; this helper command shows it again.

Production environment

Deploy kageos on Linux production

Use this when kageos should run on a remote server for a team or persistent environment.

View install-prod.sh

Build the exact Linux command

Choose one production path and copy the single command it generates.

Public HTTPS URL

Generated command

Run only one generated command for the path you chose.

 $ curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com 

Mainland China mode first uses the Aliyun registry, then falls back to the kageos release download channel and public mirrors such as DaoCloud for public dependency images when needed.

Default install

Use this for servers outside mainland China, or any server that can pull DockerHub images normally.

 $   curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com 

Mainland China install

Adds --cn so the installer automatically chooses the mainland China download or pull path and falls back when needed.

 $   curl -fsSL https://kageos.com/install-prod.sh | sudo bash -s -- --base-url https://app.example.com --cn 

Review the installer before running

Use this path when you need to inspect the script before execution.

 $   curl -fsSLO https://kageos.com/install-prod.sh 
 $   less install-prod.sh 
 $   sudo bash install-prod.sh --base-url https://app.example.com 

What this path does

Pulls from the China registry first, or falls back to the release archive/upstream image, then runs one rootful all-in-one container.
Stores persistent data under /opt/kageos/data by default; the source repository is not cloned.
Use --cn only for mainland China servers; other regions should keep the default command.
The server IP URL is only for initial validation; use a domain with HTTPS before inviting real users.
Advanced flags such as custom ports, image pinning, and container engine fallback are documented inside install-prod.sh.

After install

Open

Your --base-url

Use the same URL you passed to the installer.

Username

system

The initial production admin account.

Password

sudo kageos password

Shows the generated system password again.

Check

sudo kageos status / sudo kageos logs

Use these if the browser is not reachable after install.

What Gets Deployed

Host runtime

Rootful Podman or Docker on the Linux server, managed by the installer

Bundled infrastructure

The all-in-one image starts MySQL, NATS, and MinIO inside the kageos container

Platform services

Nginx, kageos API, web UI, system seed, and runtime services

App runtime

Generated user apps run in isolated containers managed by the platform runtime

Persistent data

Production config, generated secrets, logs, and service volumes stay on your server

Common Commands

# Check status
$ sudo kageos status
# View logs
$ sudo kageos logs
# Show password
$ sudo kageos password
# Upgrade
$ sudo kageos update

Need help?

Check the full documentation or open an issue on GitHub.

GitHub Repository Report an Issue

Install kageos

Prerequisites

Choose Platform

Run kageos locally on macOS

Install and run

Run kageos locally on Windows

Install and run

Deploy kageos on Linux production

Build the exact Linux command

Default install

Mainland China install

Review the installer before running

What Gets Deployed

Common Commands

Need help?