Install, update, and run Kaidera OS

Install paths

Homebrew, npm, and curl are distribution paths for the same Kaidera OS CLI and local product. Choose the one that best matches the target machine and package-management policy.

• Homebrew is recommended for most macOS and Linux operators.
• npm is useful where Node tooling is already the standard package path.
• curl is useful for bootstrap scripts and machines without a package manager policy yet.
• The install path should not change the product behavior or data model.

What installation creates

Installation prepares the local console runtime, verifies or creates the required local services, and gives you the current engenos CLI used for install, start, upgrade, and operational checks.

• A local console served on the standard Kaidera OS port.
• Cortex services for memory and project state.
• An app database for settings, project autonomy flags, worker overrides, and run state.
• Local command entry points for starting, upgrading, and operating the product.

Running the app

Use engenos start for normal operation. The console is the operator surface for Dashboard, workers, Dispatch, Runs, Settings, and Help. The local console should be treated as an operator tool, not as an unauthenticated public internet service.

Updates

Updates replace the application package and restart the console service. Project files, Cortex data, and the app database should remain intact. Release packages are expected to be checksum or signature verified before use.

• Homebrew: brew update and brew upgrade engenos.
• npm: npm update -g @engenai/engenos.
• CLI: engenos upgrade when the installed channel supports it.
• If an update fails health checks, rollback should preserve the last working runtime and data.

Clean shutdown and restart

Stop or restart the console when changing runtime settings that require a process restart. Worker run state is designed to be visible through the app database so operators can see what happened before and after a restart.

Troubleshooting install issues

Most first-run issues come from Docker not running, an occupied port, a missing Python version, a provider key not yet configured, or a stale service from an older local installation.

• Check Docker first if Cortex or the app database is not reachable.
• Check port 8765 if the console does not open.
• Check port 8501 if Cortex health is red.
• Check port 5500 if app database status is disconnected.
• Check Settings before assuming a worker failure is a model problem.