CMai OS Documentation

Everything you need for Server Edition, from installation through to updates. One page; jump around with the headings on the left.

Getting started

CMai OS is our own Linux distribution, built for AI development servers: it ships with its own kernel configuration, an Ed25519-signed update channel and its own ISO. Four AI tools come preinstalled — CMai (the CMai API: one key, every model) plus Claude Code, Gemini CLI and Kimi CLI — and every user works in their own workspace, isolated with rootless podman. The path from install to your first cmai command is four steps:

Requirements

A single-user trial runs on a much smaller machine (a 2 vCPU / 4 GB virtual machine, for instance); the figures above are a starting point for team use.

Downloading the ISO

The current ISO lives at releases.cmaios.net. Every release has a .sha256 file beside it; verify after downloading:

$ curl -LO https://releases.cmaios.net/cmaios-latest-amd64.iso
$ sha256sum -c cmaios-<version>-amd64.iso.sha256
# cmaios-<version>-amd64.iso: OK

On Windows, compare the output of certutil -hashfile cmaios-<version>-amd64.iso SHA256 with the value in the .sha256 file.

VirtualBox / bare-metal installation

VirtualBox: create a machine of type "Linux / Other Linux (64-bit)" with at least 2 vCPU, 4 GB RAM and a 40 GB disk. Attach the ISO to the optical drive. Set networking to Bridged so the server picks up an IP from your local network and you can reach it from a browser. EFI can be on or off.

Bare-metal: write the ISO to a USB stick (dd, Rufus, balenaEtcher) and boot the machine from it. Both BIOS and UEFI are supported; if Secure Boot is on, turn it off in the firmware settings.

The install starts automatically from the boot menu, partitions the disk, copies the packages and reboots. Nothing is needed from you while it runs.

First boot and the wizard

On the first boot after installation you will see a card on the console (the physical screen or the virtual machine window):

Open this in a browser to finish setup

  Address        https://192.168.1.40:8443
  Setup code     Q63X-FE73

  On the certificate warning choose "Advanced → Proceed".
  SSH and the other services stay closed until setup is finished.

1. Open the address. The panel uses a self-signed certificate; on the browser warning choose Advanced → Proceed.
2. Enter the setup code. The one-time 8-character code from the card (XXXX-XXXX). Nobody without console access can open the wizard.
3. Licence key. Your key, in the form CMAI-XXXX-XXXX-XXXX-XXXX. The server contacts the licence service and the key binds to this device.
4. CMai API key. The cm-… key you created at app.cmai.tr/customer/keys. This single key is written into every user's workspace and the CMai CLI (cmai) runs on it; see The CMai API and the AI tools.
5. Admin account. A username plus either an SSH public key or a password. A key is recommended: if you supply one, password login is never enabled for that user.

When the wizard finishes, the console card switches to CMai OS ready and shows the SSH line, the panel address and a licence summary. SSH is now open.

Connecting

$ ssh admin@192.168.1.40
CMai OS ready  ·  workspace: admin  ·  /workspace
admin@cmai:/workspace $ cmai

What a workspace is

Every user who logs in over SSH lands not on the host but in their own workspace: a container of their own, run with rootless podman. Inside it the CMai CLI (cmai), claude, gemini, kimi, compilers and git are all ready. The home directory is HOME=/workspace and it persists; your files survive a container restart. CPU, RAM and process count are quota-bound per user (set with cmai user add).

The CMai API and the AI tools

CMai API — one key, every model. CMai is the enterprise AI platform built by CMApps (cmai.tr): chat, image, audio-video and embeddings behind one standard API (OpenAI-compatible Chat Completions), with credit management and live monitoring. In CMai OS, the single CMai API key you enter at the AI step of the wizard is written into every user's workspace; in the workspace, cmai (or cmai code) starts CMai CLI, the CMai coding agent that lives in your terminal and runs on that API (default model cmai-pro).

CMai CLI (@cmapps/cmai-cli) is preinstalled in every workspace and connects to the CMai API automatically with the server's key (CMAI_API_KEY / CMAI_MODEL / CMAI_BASE_URL). It has automatic memory, skills, sub-agents and MCP support: cmai -p "…" runs a one-shot command, cmai mcp add … adds an MCP server, and a CMAI.md at the project root gives it standing instructions. Settings persist under /workspace/.cmai. Models: cmai-pro, cmai-balanced, cmai-fast, cmai-vision. To install it on your own machine: npm install -g https://cmai.tr/downloads/cmai-cli-latest.tgz.

1. Get a key: create one at app.cmai.tr/customer/keys (it starts with cm-…).
2. Enter it: at the AI step of the wizard; to change it later, use the local admin panel at https://<ip>:8443.
3. Use it: log in over SSH and type cmai (cmai code does the same thing).

admin@cmai:/workspace $ cmai
╭─ CMai CLI · cmai-pro ─────────────────╮
│  > Run the tests and fix the failing ones  │
╰───────────────────────────────────────╯

Environment variables ready in every workspace — any OpenAI-compatible tool (SDKs, editor extensions, your own scripts) reaches the CMai API with no extra configuration:

API endpoints: POST /v1/chat/completions (SSE streaming, tool/function calling, text · image · PDF · audio · video input), /v1/embeddings, /v1/files, /v1/models. Authentication is Authorization: Bearer cm-…. Seven models: cmai-pro (default, 200K context), cmai-balanced (200K), cmai-fast (128K), cmai-vision (1M), cmai-av (audio-video, 1M); for embeddings, cmai-embed-small and cmai-embed-large (high quality, 8K). Full reference: docs.cmai.tr/docs.

$ curl "$CMAI_BASE_URL/chat/completions" -H "Authorization: Bearer $CMAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"cmai-fast","messages":[{"role":"user","content":"Hello"}]}'

Host commands

Commands on the host (cmai …, systemctl, journalctl) are not visible from inside a workspace. The admin runs them through SSH's command argument, with sudo:

$ ssh admin@192.168.1.40 "sudo cmai license status"
$ ssh admin@192.168.1.40 "sudo cmai user add ayse --cpus 2 --mem 4096 --ssh-key 'ssh-ed25519 AAAA…'"
$ ssh admin@192.168.1.40 "sudo journalctl -u cmai-workspace-ayse -f"

You can also type the same commands directly on the server's console.

CLI reference

The admin CLI cmai runs on the host and needs root (sudo); do not confuse it with the CMai CLI (cmai) inside a workspace. Its subcommands:

Licensing

CMai OS uses online activation (much as Windows does): the key binds to a device once, and the server verifies its licence online.

Plans: Trial (14 days, 1 user, free), Solo (1 user, $29/mo), Team (5 users included, up to 20; $99/mo, $19/mo per extra user), Enterprise (20+ users, multiple servers; from $499/mo per server, quoted). Prices are in USD and exclude VAT, and AI usage fees are not included; the current list is at cmaios.com/#planlar. For a key, write to isgelistirme.ortaklik@cmapps.com.tr.

Admin panel

The address the wizard ran on becomes the admin panel after installation: https://<ip>:8443. You sign in with the admin account you created in the wizard. The licence page shows:

• Licence status (active / locked / no licence), plan, user count and validity
• Device id, connection state and the licence server address
• Renew: sync with the server immediately
• New licence key / change key: the browser route to unlocking a locked server
• CMai API key: change the key entered in the wizard (it is written into every workspace; the CMai CLI runs on it)
• Connection summary: the SSH line, the admin name, the version

The panel is designed to be reached from the local network or the server's IP; its certificate is self-signed.

Security

CMai OS ships with military-grade encryption standards (AES-256 / Ed25519 / TLS 1.3) and strict defaults. Every measure below is active out of the box; none of them needs extra configuration.

Full-disk encryption, FIPS certification and hardware-backed key storage (mandatory TPM) are not in this release; they are being evaluated on the roadmap. For security reports, see security.txt.

Troubleshooting

SSH: Permission denied (publickey)

The server only accepts key-based logins and does not recognise the key you offered. Checklist:

• Make sure you are using the right key: ssh -i ~/.ssh/id_ed25519 admin@<ip>
• If you chose a password in the wizard, password login is enabled; if your client keeps getting stuck trying keys, use ssh -o PubkeyAuthentication=no admin@<ip>
• To add another user's key, as the admin: sudo cmai user add <name> --ssh-key "…"

"Your workspace is being prepared"

On the first login the user's container is created; if the workspace image is still being prepared this can take a few minutes. Watch the progress from the host:

$ ssh admin@<ip> "sudo journalctl -u cmai-workspace-<name> -f"

If it hangs, run sudo cmai user stop <name> then sudo cmai user start <name>; for overall health, sudo cmai doctor.

The console card shows no IP

The card may have been drawn before the network interface got an address. Press Enter on the console and it is redrawn with current information. If there is still no IP, check DHCP and — in a virtual machine — that networking is set to Bridged.

The system is locked

If the card says System locked — licence not valid it also prints the reason (expired, suspended, licence service unreachable). Enter a new key from the panel or with cmai license activate, as described under Licensing; if it is a connectivity problem, use cmai license renew.

Releases and updates

The version format is 0.1.0-dev.<n>+<sha> — n is the build counter and sha the short git hash of the source. You can see the installed version in the output of cmai license status and in the panel; the -BUILD.txt file beside each ISO holds the build details.

Updates are managed with cmai update check / cmai update apply; the channel can be stable, beta or nightly. A package-based apt channel (apt.cmaios.net) is coming; until then, new releases are published as ISOs at releases.cmaios.net.

Frequently asked

For general product questions (pricing, plans, hardware) see cmaios.com/#sss.

Glossary

Workspace

An isolated container belonging to one user, run with rootless podman. SSH logins land directly in it, and HOME=/workspace is persistent.

User count

The number of users the licence allows. Every "cmai user add" consumes one user seat.

Server limit (max devices)

How many servers the same key may be active on at once.

Device id

A unique identifier derived from the server at activation and bound to the key; strengthened by TPM where one is present.

Verification

The server verifying its licence through license.cmaios.net; no user action is needed.

Lock mode

The state entered while a licence is invalid: SSH, workspaces and published projects stop, and data is preserved.

Channel

The update stream: stable, beta or nightly. Selected with "cmai update channel".

Console card

The status card shown on the physical console at first boot and afterwards: panel address, setup code, SSH line, licence summary.

Setup code

The one-time 8-character code (XXXX-XXXX) needed to open the wizard; it appears only on the console.

CMai API key

The cm-… key taken from app.cmai.tr/customer/keys. Entered once in the wizard and written into every workspace as CMAI_API_KEY; the CMai CLI ("cmai") runs on it.

Key hint

The last four characters of a key (CMAI-…-XXXX). Shown in the portal and in emails in place of the whole key.