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 either own 80/443 directly or run behind an edge proxy such as Caddy or Nginx

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.ai/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 View uninstall-prod.sh

Build the exact Linux command

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

Public HTTPS URL

Generated command

Run one path. Proxy mode assumes a local port 10001 upstream.

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

Mainland China mode uses Alibaba Cloud Container Registry for Kageos image distribution, public mirrors such as DaoCloud , and Goproxy.cn supported by Qiniu Cloud for Go module downloads when needed.

Default install

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

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

Behind an existing reverse proxy

Use this when Caddy, Nginx, or a load balancer already owns ports 80/443 and forwards traffic to Kageos.

 $   curl -fsSL https://kageos.ai/install-prod.sh | sudo bash -s -- --base-url https://app.example.com --tls-mode external --http-port 10001 

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.ai/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.ai/install-prod.sh 
 $   less install-prod.sh 
 $   sudo bash install-prod.sh --base-url https://app.example.com 

Clean uninstall

Use this before reinstalling a failed test server. --purge deletes /opt/kageos data.

 $   curl -fsSL https://kageos.ai/uninstall-prod.sh | sudo bash -s -- --yes --purge 

What this path does

Pulls from the China registry first, or falls back to the 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.
--cn also configures Go module downloads through mainland China friendly proxy settings for workspace app builds.
The server IP URL is only for initial validation; use a domain with HTTPS before inviting real users.
Use --tls-mode external when TLS is terminated by Caddy, Nginx, a cloud load balancer, or another edge proxy.
If the host FORWARD policy blocks container traffic, the installer adds scoped allow rules for the Kageos public ports.
If localhost works but the public URL still times out, run sudo kageos doctor and check cloud firewall rules.
Clean uninstall is available through uninstall-prod.sh; add --remove-images only when you also want to repull images.
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 doctor

Use this if localhost works but the public URL is not reachable.

Choose the Production Shape

Pick the shape that matches the host before running the installer. The public URL passed through --base-url should always be the URL users open in the browser.

Clean server

Kageos owns 80/443

Use the default command when nothing else is listening on the public web ports. Kageos handles HTTP, HTTPS, and redirects inside the all-in-one container.

Existing edge

Caddy or Nginx owns TLS

Use --tls-mode external when a reverse proxy already listens on 80/443 and forwards to Kageos on a private HTTP port.

First validation

IP and HTTP trial

Use an HTTP IP URL only to confirm the server and image path. Switch to a domain and HTTPS before inviting real users.

Reverse Proxy Deployment

This is the recommended path when a host already runs Caddy, Nginx, a cloud load balancer, or a platform ingress. Keep the proxy on 80/443 and let Kageos serve local HTTP on 10001.

Install Kageos behind the proxy

The canonical URL remains HTTPS because that is what users open. external means TLS terminates before traffic reaches Kageos.

$ curl -fsSL https://kageos.ai/install-prod.sh | sudo bash -s -- \
 --base-url https://app.example.com \
 --tls-mode external \
 --http-port 10001

Caddy example

Caddy automatically obtains certificates when the DNS A record points to this server and public TCP 80/443 are open.

app.example.com {
 encode zstd gzip
 reverse_proxy 127.0.0.1:10001
}

Nginx example

Use this when another certificate workflow already manages Nginx TLS.

location / {
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_pass http://127.0.0.1:10001;
}

Port policy

In proxy mode, expose 80/443 to the internet for the edge proxy. Do not add the Kageos upstream port to a public cloud security group unless you intentionally want direct access.

# Public ingress
80/tcp, 443/tcp -> Caddy or Nginx
# Local upstream
127.0.0.1:10001 -> Kageos

Access Troubleshooting Checklist

Split the problem into server, proxy, DNS, and client cache. A successful server-side HTTPS probe means Kageos and the reverse proxy are already serving correctly.

Run on the server

$ curl -4 ifconfig.me; echo
$ dig +short app.example.com A @1.1.1.1
$ sudo ss -lntp | grep -E ':(80|443|10001)\s'
$ curl -I http://127.0.0.1:10001
$ curl -I https://app.example.com
$ sudo journalctl -u caddy -n 100 --no-pager -l

Run from the client

$ dig +short app.example.com
$ curl -Iv https://app.example.com
# macOS DNS cache
$ sudo dscacheutil -flushcache
$ sudo killall -HUP mDNSResponder
# Chrome cache
chrome://net-internals/#dns
chrome://net-internals/#sockets

What Gets Deployed

L1

Host runtime

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

L2

Bundled infrastructure

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

L3

Platform services

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

L4

App runtime

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

L5

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
# Diagnose public access
$ sudo kageos doctor
# Show password
$ sudo kageos password
# Upgrade
$ sudo kageos update
# Clean uninstall
$ curl -fsSL https://kageos.ai/uninstall-prod.sh | sudo bash -s -- --yes --purge

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

Behind an existing reverse proxy

Mainland China install

Review the installer before running

Clean uninstall

Choose the Production Shape

Kageos owns 80/443

Caddy or Nginx owns TLS

IP and HTTP trial

Reverse Proxy Deployment

Install Kageos behind the proxy

Caddy example

Nginx example

Port policy

Access Troubleshooting Checklist

Run on the server

Run from the client

What Gets Deployed

Common Commands

Need help?