Update to Kora

{
  "description": "Read when installing, configuring, operating, updating, or debugging a self-managed Kora Platform deployment: the install.sh bootstrap, koractl lifecycle commands (install, configure, start, stop, status, logs, doctor, update), install modes, and license activation.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 344
    },
    {
      "relative_path": "assets/kora-mark.png",
      "size_in_bytes": 24826
    },
    {
      "relative_path": "references/install.md",
      "size_in_bytes": 9617
    },
    {
      "relative_path": "references/operate.md",
      "size_in_bytes": 3455
    },
    {
      "relative_path": "references/update-and-license.md",
      "size_in_bytes": 6544
    }
  ],
  "name": "kora-self-host",
  "skill_md_contents": "---\nname: kora-self-host\ndescription: \"Read when installing, configuring, operating, updating, or debugging a self-managed Kora Platform deployment: the install.sh bootstrap, koractl lifecycle commands (install, configure, start, stop, status, logs, doctor, update), install modes, and license activation.\"\n---\n\n# Kora Self-Host Operations\n\nUse this skill when the user wants to install Kora on a machine they control,\nor to operate an existing self-managed deployment. Using a running Kora from\nthe terminal (signup, login, organizations, workflows) is the `kora-cli`\nskill, not this one.\n\nDo not use this skill for Kora SaaS. A SaaS user signs in to an existing\nregional Kora service and uses `kora-cli`; they do not run `install.sh`, manage\nDocker Compose, activate a deployment license, or use `koractl`. If the target\nmode is unclear, ask whether the user wants Kora SaaS or a deployment on\ninfrastructure they control before running any command.\n\n## Mental Model\n\nA self-managed Kora deployment is a Docker Compose bundle driven entirely by\nthe single `./koractl` command from the install directory. Operators do not\nrun `docker compose` directly except through the advanced escape hatch.\n\nSupported platforms: macOS with Docker Desktop or a compatible Docker/Compose\nsetup, and Linux with Docker Engine plus the Docker Compose plugin. V1 does\nnot support native Windows, Dockerless runtimes, or bundled native\nPostgres/Temporal/OpenSandbox. The installer fails with remediation\ntext when Docker or the Compose plugin is missing.\n\nInstall directory layout (bundle files plus runtime-generated files):\n\n```text\nkora-platform/\n  koractl\n  compose.yaml\n  .env.example\n  Caddyfile\n  opensandbox.toml\n  init-db.sql\n  temporal/        # bundled schema and namespace setup\n  LICENSE.md\n  COPYRIGHT\n  THIRD_PARTY_NOTICES.md\n  .env             # generated configuration\n  license/         # license material and deployment token\n  state/           # chat workspaces, workflow artifacts\n  .rendered/       # rendered OpenSandbox config\n```\n\nDo not call Docker cleanup commands directly; `koractl` owns lifecycle details\nsuch as OpenSandbox cleanup and is the supported operator surface.\n\n`license/license-deployment-token` is a bearer secret: keep it owner-readable\nonly and never log it, commit it, or send it to support. The signed\n`license.json` is entitlement material, not a bearer secret.\n\nIn the kora-platform source repository, `pnpm dev:up` is the repo-development\npath. Never use it for self-managed installs, and never point users at this\nskill for repo development.\n\n## Install\n\nThe public bootstrap downloads the latest release bundle, verifies its\nchecksum, extracts it to a temporary directory, and delegates target selection\nand installation to the bundled `./koractl bootstrap-install`:\n\n```sh\ncurl -fsSL https://kora.raw-labs.com/install.sh | bash\n```\n\nOnline installs use an install session owned by Kora Accounts. Free, Pro,\nTeams, and account-managed Enterprise/evaluation are the common online paths,\nbut the signed connectivity policy rather than the commercial plan label owns\nthe deployment's Cloud dependency. Without an install-session token, the\nterminal prints a Kora Accounts URL; the human completes sign-in, plan\nselection, and checkout in the browser while the terminal polls. When Kora\nAccounts approves the session, the installer writes the license material and\nstarts Kora. When driving this as a coding agent: run the command, surface\nthe printed URL to the user, and wait — browser cancellation or expiry is\nreported back to the terminal instead of hanging until the polling timeout.\n\nPick an install mode up front:\n\n- **local** — one person, one machine. Defaults to\n  `$HOME/.kora/kora-platform` and `http://localhost:3000`, plain HTTP, first\n  signed-up user becomes platform admin.\n- **server** — a VM or host reachable by a team. Defaults to\n  `/opt/kora-platform`, HTTPS via Caddy, and requires a login allowlist.\n  Server installs require verified SSO admin bootstrap; unverified local-auth\n  first-user bootstrap is limited to local single-machine evaluation.\n- **offline** — an air-gapped deployment whose license files arrive out of band\n  and whose signed connectivity policy does not require Kora Accounts.\n\nFor non-interactive automation, pass flags to the bootstrap or set the\nmatching environment variables:\n\n```sh\ncurl -fsSL https://kora.raw-labs.com/install.sh | bash -s -- --mode server --dir /opt/kora-platform\n```\n\n`--mode` answers the local/server/offline prompt; `--dir` answers the\ninstall-directory prompt. `KORA_INSTALL_MODE` and `KORA_INSTALL_DIR` are the\nenvironment equivalents. `KORA_NONINTERACTIVE=1` makes prompts use defaults\nor provided environment values, but a useful fully non-interactive install\nstill needs explicit values for required server, model, access, and license\nconfiguration.\n\nFor a server install without prompts, provide the mode, directory, public\nhostname, model settings, verified SSO admin bootstrap config, login allowlist,\nand either an install-session token or a plan to complete the printed browser\napproval. Server mode requires OIDC or `local+oidc`; local email/password\nfirst-user bootstrap is only for local single-machine evaluation.\n\n```sh\nexport KORA_NONINTERACTIVE=1\nexport KORA_PUBLIC_DOMAIN=kora.example.com\nexport KORA_AUTH_MODE=oidc\nexport KORA_BOOTSTRAP_ADMIN_EMAILS=admin@example.com\nexport KORA_AUTH_ALLOWED_EMAILS=admin@example.com,@example.com\nexport KORA_OIDC_ISSUER=https://idp.example.com\nexport KORA_OIDC_CLIENT_ID=kora-platform\nexport KORA_OIDC_CLIENT_SECRET=\"$OIDC_CLIENT_SECRET\"\nexport KORA_OIDC_REDIRECT_URI=https://kora.example.com/api/v1/auth/oidc/callback\nexport KORA_OIDC_SCOPES=openid,email,profile\nexport KORA_OIDC_PROVISIONING=allowlist_user\nexport KORA_CHAT_MODEL_INPUT=anthropic/claude-opus-4-6\nexport KORA_CHAT_MODEL_API_KEY_INPUT=\"$MODEL_PROVIDER_API_KEY\"\n# Optional: export KORA_CHAT_MODEL_BASE_URL_INPUT=https://gateway.example.com/v1\nexport KORA_AGENT_MODEL_INPUT=anthropic/claude-opus-4-6\nexport KORA_AGENT_MODEL_API_KEY_INPUT=\"$MODEL_PROVIDER_API_KEY\"\n# Optional: export KORA_AGENT_MODEL_BASE_URL_INPUT=https://gateway.example.com/v1\n\ncurl -fsSL https://kora.raw-labs.com/install.sh | \\\n  bash -s -- --mode server --dir /opt/kora-platform --install-session kora_ins_...\n```\n\n`KORA_CHAT_MODEL_INPUT` and `KORA_AGENT_MODEL_INPUT` must be supported\n`koractl` Pi model choices. Use `anthropic/claude-opus-4-6` unless the\noperator explicitly chooses another listed model. The chat model powers\nuser-facing conversations in the Kora web UI; the agent model powers Kora agent\nexecution work, such as coding tasks and automation. Operators can use the same\nmodel and API key for both, or split them for different cost, latency, or\ncapability settings. `KORA_AGENT_MODEL` is the deployment fallback for\ncapabilities that omit `agentConfig.model`; organization owners can select the\nworkflow default and add access for other catalog models in Platform Settings >\nModels. The matching deployment-fallback model API\nkeys are required before install or start can continue; get them from the\nselected provider's account/API-key page, such as Anthropic, OpenAI, Google,\nxAI, Groq, OpenRouter, Mistral, DeepSeek, Moonshot, or Z.ai.\nUse the optional scoped base-URL inputs only for a compatible gateway or private\nprovider endpoint. Blank keeps the selected provider's native endpoint; never\nembed credentials, query strings, or fragments in the URL.\n\nReruns into an existing install directory must state intent with\n`--existing-action` or `KORA_EXISTING_INSTALL_ACTION` (one of `start`,\n`update`, `configure`, `relink`, `reinstall`, `cancel`). Other bootstrap\nflags are `--install-session <token>`, `--cloud-base-url <url>`, and\n`--version <release>`. The version-specific `--apply-0.12-migration` flag is\nreserved for the documented partial-0.12 recovery in the update reference.\n\nMode defaults, install sessions, manual bundle installs, and the required\nconfiguration checklist are in `references/install.md`.\n\n## Verify\n\nAfter install or any lifecycle change:\n\n```sh\n./koractl status\n./koractl doctor\n```\n\n`status` summarizes the stack as `stopped`, `starting`, `healthy`, or\n`unhealthy`, then prints Compose service status and the basic HTTP health\nresult. `doctor` checks Docker, Compose, env placeholders, license files,\ndeployment-token permissions, disk/RAM capacity, and public URL consistency,\nand prints remediation text instead of stack traces. A healthy local install\nserves the web app at `http://localhost:3000`.\n\n## Command Table\n\n```sh\n./koractl install\n./koractl configure\n./koractl configure models\n./koractl configure access\n./koractl configure license\n./koractl start [--apply-0.12-migration]\n./koractl stop\n./koractl restart [service]\n./koractl status\n./koractl logs [service]\n./koractl doctor\n./koractl update [version] [--terminate-running] [--apply-0.12-migration]\n./koractl license status\n./koractl license activate\n./koractl license install-file\n./koractl version\n```\n\nAdvanced support can use `./koractl compose <docker-compose-args...>`, but\nprefer the named commands.\n\n## Handoff To Product Use\n\nOnce `./koractl status` reports healthy, account and workspace work moves to the\nweb app at the deployment base URL or to the Kora CLI — read the `kora-cli`\nskill. On a local-mode install, the first user to sign up becomes platform\nadmin. On server installs, sign in with SSO using one of the configured verified\nplatform-admin bootstrap emails.\n\n## Which Reference To Read Next\n\n- `references/install.md` — mode defaults, online install sessions, manual\n  release installs, existing-install reruns, and the required configuration\n  checklist\n- `references/operate.md` — start/stop/restart semantics, status, logs,\n  doctor, model and access configuration, and advanced files\n- `references/update-and-license.md` — updates, forward recovery, license\n  operations, and deployment-token hygiene\n"
}