Browse and search documentation
Download and install
Five steps to a running platform: download a package, verify and extract it, run one command, sign in, and import a License. Connecting your first host follows, and the end of the page carries deployment reference material and the common failures.
On this page
Step 1: download a package, online or offline
Both packages install exactly the same thing: the same installer, the same topology, the same images, and the same command later on. They differ in one respect only — whether the images are pulled during installation or already inside the package.
If the installation host can reach public image registries, take the online package: 36.4 KB, with the images pulled from quay.io/chrono during installation. On an isolated network take the offline package: 551 MB, images included, and the installation never touches the network. When in doubt take the offline one — it installs just as well on a connected host, it only takes longer to download.
- chronoops-online-1.1.1.tar.gz
Online installation. The installation host must be able to reach
quay.io/chrono. - chronoops-offline-1.1.1.tar.gz
Offline installation. Contains all five images — backend, console frontend, PostgreSQL/pgvector, Redis and guacd — and never touches the network during installation.
Step 2: verify and extract
Verifying confirms that what you downloaded is neither damaged nor substituted. Continue only when you see OK; do not extract a file that fails.
base=https://www.aiops.red/downloads/bundle
curl -fLO ${base}/chronoops-offline-1.1.1.tar.gz
curl -fLO ${base}/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar xzf chronoops-offline-1.1.1.tar.gz
cd chronoops-offline-1.1.1For the online package substitute chronoops-online-1.1.1.tar.gz and leave the rest unchanged. If a download breaks off, resume it with curl -C - -fLO rather than starting over.
If the check fails, download again and re-check. If it still differs, contact weiwendi@aiops.red rather than installing anyway.
Before loading any image the offline package checks them again against its own images/SHA256SUMS, so a damaged extraction or a modified directory is caught rather than half-installed.
Step 3: one command
Run this in the directory you changed into at the end of the previous step. The command is the same for both packages; the installer recognises which one it has.
- It verifies and prepares the images: the offline package loads them locally, the online one pulls them from
quay.io/chrono. - It generates the database password, the platform authentication and credential-encryption material and a one-time administrator password in the local state directory. None of these are printed to the terminal.
- It generates the console HTTPS certificate and the Agent gateway certificates, and checks that the ports it needs are free.
- It starts six containers, runs the database migrations and waits for the health checks to pass.
sudo CHRONOOPS_QUICKSTART_ADVERTISE_HOST=<被管理主机能访问到的 IP 或域名> \
tools/quickstart.sh --yesIt finishes by printing the console address, the Agent endpoint, the tenant and administrator names, where the one-time password file lives and the SHA-256 fingerprint of the console CA. Work from the values it printed, not from the examples on this page.
Running the command again is safe: it resets no existing administrator password and overwrites no generated key. Rerun it after changing the advertised address or a port and the certificates are updated to match.
Job execution is on by default: an approved job really does run commands on its target host. That switch is only the outermost gate — IAM permissions, approval and MFA, command policy and audit are all still checked on every run. To stop all remote execution, while troubleshooting or in a rehearsal environment, rerun with CHRONOOPS_JOB_EXECUTION_ENABLED=false; the installer remembers it, and a later rerun without the variable will not switch it back on.
Step 4: open the console and sign in
Open the https://<advertised address>:8443 the installer printed. The first visit raises a certificate warning, which is expected: the certificate comes from a CA this installation generated rather than a public one. While evaluating, choose to continue past the warning; the next section covers how to make it go away for good.
- Sign in as
adminwith the one-time password. - Changing the password is mandatory at first sign-in. Until you do, nothing else in the console works and every request answers that the password must be changed first.
- Sign out, sign in again with the new password and confirm the change really took.
- Delete the one-time password file once you have confirmed.
| What to enter | Where to find it |
|---|---|
| Tenant | default |
| Username | admin |
| Password | The ~/.config/chronoops/quickstart/initial-admin-password file under the installing account — root’s home directory if you used sudo |
Step 5: import a License to unlock features
By now the platform is installed and you can sign in. Whether you can actually manage hosts depends on importing a signed License bound to your organization.
Without one the console opens normally and you can look around; onboarding hosts, running jobs and similar features each report that they are not licensed. That is a licensing matter, not a failed installation, and no reinstallation is needed.
- To request one: write to weiwendi@aiops.red and describe your operating system, CPU architecture and the number of nodes you plan to manage.
- Import it on the console License page. No reinstallation and no container restart are required.
- The
licenses/trust-bundle.jsonin the package is a different thing: verification public keys only, bound to no customer, identical for everyone, and required for the platform to start at all. It always ships with the package and needs no attention from you.
Getting rid of the certificate warning (optional)
The console’s HTTPS certificate is issued by a CA this installation generated, which no public CA vouches for, so browsers flag it as untrusted. The connection is still encrypted; the browser simply cannot confirm on your behalf who is at the other end.
Pick the one that matches where you are; you do not need all three:
| Your situation | What to do |
|---|---|
| Evaluating, one or two people | Nothing. Choose to continue past the browser warning. |
| Rolling out to a team, no proper certificate yet | Distribute the generated ca.crt to everyone who opens the console and have each of them trust it once. Commands below. |
| Production | Use your own certificate instead of the self-signed one. See the last item in this section. |
# Debian / Ubuntu
sudo cp ca.crt /usr/local/share/ca-certificates/chronoops-console.crt
sudo update-ca-certificates
# RHEL / openEuler / Kylin
sudo cp ca.crt /etc/pki/ca-trust/source/anchors/chronoops-console.crt
sudo update-ca-trust
# macOS
sudo security add-trusted-cert -d -k /Library/Keychains/System.keychain ca.crt
# Windows
certutil -addstore -f Root ca.crtca.crt sits at agent-gateway/console-ca/ca.crt inside the state directory, and the installer printed both its full path and its SHA-256 fingerprint. Check the fingerprint before running any of these commands: trusting a CA means trusting every certificate it issues, so never install one you have not verified.
This CA covers console HTTPS only and is separate from the one that issues Agent client certificates; neither affects the other. External integrations that call the console’s https address — alert forwarding, webhooks — need to trust it too.
In production, replace it with your own certificate: put the certificate and key at agent-gateway/console/tls.crt and tls.key inside the state directory and run the installer again. It recognises material it did not issue, reads it without overwriting, and stops telling you to distribute a CA. The key must be an unencrypted PEM matching the certificate, and the certificate must carry SANs; on a mismatch, missing SANs or a missing key the installer stops and says why without touching your files.
Connect your first host
With the platform running, assets, jobs and inspections all need at least one host. Create a registration token in Agent management and the console hands you the enrollment command for that host; copy the matching package below onto the target machine and run what it gave you.
The token is a single-use credential: by default it works once and can be bound to one specific host. During enrollment the private key is generated on the target machine and only a certificate signing request travels upstream, with the platform issuing the client certificate for the identity the token established. You prepare no certificate files yourself.
- chronoops-agent-1.1.0-linux-amd64.tar.gz
Linux x86_64 (amd64). For first installation; the console can upgrade it online afterwards.
- chronoops-agent-1.1.0-linux-arm64.tar.gz
Linux ARM64 (aarch64). For first installation; the console can upgrade it online afterwards.
- chronoops-agent-1.1.0-linux-loong64-preview.tar.gz
Linux LoongArch64 preview build, for evaluation and verification only; not claimed at the same level as x86_64 and ARM64, so keep it off production hosts.
- chronoops-agent-1.1.0-windows-amd64.zip
Windows x86_64 (amd64). For first installation, or for replacing an installed Agent during a maintenance window; console-initiated online upgrade is not supported.
curl -fLO https://www.aiops.red/downloads/agent/1.1.0/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMSEvery line must report OK. On Windows run certutil -hashfile chronoops-agent-1.1.0-windows-amd64.zip SHA256 and compare the result character by character with the checksum listed above.
Once enrolled, confirm systemctl is-active chronoops-agent reports active on the target host, then check the console shows it online. Connect your first Agent covers enrollment and troubleshooting in full.
Common failures and what to do
| What you see | Cause and next step |
|---|---|
| Agents cannot reach the platform | Usually the advertised address was left on a loopback address. Rerun the installer with CHRONOOPS_QUICKSTART_ADVERTISE_HOST set to an address the managed hosts can actually reach; the certificate and enrollment address are updated together. |
| Pulling the images fails | The host cannot reach the public image registry. Confirm with docker pull quay.io/chrono/chronoops-backend:1.1.1; if it genuinely cannot, switch to the offline package, which carries the images. |
| An image archive fails verification | The offline package downloaded incompletely, extracted badly, or the extracted directory was modified. Delete it, re-check the package SHA-256 and extract again. The installer will not load an image that fails verification. |
| A port is reported as busy | Another program or deployment holds a port the installer needs. Free it or pick another through an environment variable. The installer stops before touching any container, so nothing is half-installed. |
| The browser warns the certificate is untrusted | Expected. Continue past it while evaluating; see “Getting rid of the certificate warning” above to remove it properly. |
| Every action says the password must be changed first | The mandatory first-sign-in password change is not finished. Complete it before using anything else. |
| A feature reports it is not licensed | That feature is outside your licensed scope, or no License has been imported yet. It is a licensing matter rather than a failed installation; contact us to confirm your scope. |
| The installer reports a missing License trust bundle | The licenses/trust-bundle.json inside the package is gone. Extract the complete package again instead of copying part of the directory. |
Deployment reference: services, ports and images
The following is what a single-node deployment consists of, for architecture and security review. The two delivery files behind it can also be downloaded on their own; they are exactly the files inside the install package, with nothing rewritten.
| Service | Role | Published port |
|---|---|---|
| postgres | Business data, audit records and vector search (PostgreSQL 16 with pgvector) | Not published to the host |
| redis | Runtime cache | Not published to the host |
| backend | The backend API, which also terminates the Agent gateway | 9090 (Agent enrollment and traffic, mTLS) |
| frontend | The console web entry point, forwarding API and WebSocket traffic to the backend | 8080 (308 redirect) and 8443 (HTTPS) |
| access-gateway | The privileged-access data plane, which resolves managed credentials in an isolated process | Not published to the host |
| guacd | The RDP and VNC graphical protocol backend | Not published to the host |
- quickstart.yml
The Compose topology of the single-node all-in-one deployment: containers, ports, volumes and runtime switches.
- quickstart.sh
The installer inside the package: it settles the online or offline form, generates local runtime secrets and self-signed PKI, prepares the images, starts the containers and prints the first-login details.
The images are quay.io/chrono/chronoops-backend and quay.io/chrono/chronoops-frontend, pinned to exact versions by the image index inside the package. The online package pulls them from that public repository and the offline package loads the archives it carries; they are the same images either way.
Plan backup and retention for each of the six volumes separately: a database backup does not contain job output, session recordings or release artifacts.
The database and cache are reachable only inside the Compose network, and the Agent channel uses mTLS. A production domain, publicly trusted certificates and firewall rules still have to be planned for the target environment.
What is supported and what this page does not promise
- This page produces a single-node all-in-one environment. Multi-node, high-availability and Kubernetes deployments are out of scope; see “When a single node is not enough” in Before you install.
- Linux amd64 and arm64 are the architectures currently delivered for the Agent. LoongArch64 is a preview build, and the Windows package covers first installation or maintenance-window replacement only, without console-initiated online upgrades.
- A customer-bound signed License is not downloadable from this page; contact us for one.
- Confirm compatible combinations of operating system, CPU architecture and database by testing the target environment. ChronoOps does not claim certification under China’s localized-stack, commercial-cryptography or classified-protection schemes.
- A completed installation is not a production-ready one: a production domain and certificate, a rehearsed backup and restore, account and permission design and approval policy all still have to be prepared for the target environment.
Send your deployment version, page and a redacted description so we can investigate and update the guide.
weiwendi@aiops.red