Install kageos

Run kageos locally, deploy it directly on Linux, or put it behind an existing edge proxy. 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; production instances use host ports from 10001 while Caddy or Nginx owns 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.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

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.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.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 only the selected instance data.

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

What this path does

Each run creates the next isolated instance (instance-01, instance-02, ...) and selects the first free host port from 10001.
Each instance stores data under /opt/kageos/instances/<instance-id>/data; 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.
When exactly one instance exists, sudo kageos update works without an instance id. Multiple instances require an explicit id or --all.
Clean uninstall is available through uninstall-prod.sh; data is deleted only when --purge is explicit.
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.

Advanced: move high-traffic web assets to S3 and a CDN

The default needs no extra configuration: built-in Nginx serves the web UI and is the simplest choice for most small and medium deployments. Enable this only when static assets are consuming meaningful bandwidth on the main server.

Prepare an S3-compatible bucket and map a CDN hostname to it. The CDN must allow public GET requests and CORS from your kageos origin. The command contains only public settings; the installer securely prompts for the access and secret keys.

curl -fsSL https://kageos.ai/install-prod.sh | sudo bash -s -- --web-assets s3 --web-s3-endpoint https://s3.example.com --web-s3-bucket kageos-assets --web-cdn-url https://cdn.example.com

The keys are not command-line arguments and are not passed to the long-running kageos container. The root-only instance configuration is reused by sudo kageos update. Automation can inject KAGEOS_WEB_S3_ACCESS_KEY_ID and KAGEOS_WEB_S3_SECRET_ACCESS_KEY.

One Standard Production Shape

kageos always runs on an isolated upstream port starting at 10001. Use the IP and assigned port first, then point Caddy or an existing gateway at the same instance when a domain is ready.

First install

IP and port 10001

The installer creates instance-01 and exposes it on the first free host port from 10001. It never takes over 80/443.

Existing edge

Caddy or Nginx owns TLS

Keep the gateway on 80/443 and forward the domain to the instance port. HTTPS base URLs automatically use external TLS mode.

More instances

Automatic isolation

Run the installer again to create instance-02 on 10002, with its own container, configuration, and data directory.

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

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

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

Behind an existing reverse proxy

Mainland China install

Review the installer before running

Clean uninstall

One Standard Production Shape

IP and port 10001

Caddy or Nginx owns TLS

Automatic isolation

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?