# CMai OS Documentation (full text)

Source: https://docs.cmaios.com/en/ · Product: https://cmaios.com/en/ · ISO: https://releases.cmaios.net/en/ · Portal: https://portal.cmaios.com/ · Contact: isgelistirme.ortaklik@cmapps.com.tr
Turkish version: https://docs.cmaios.com/llms-full.txt
Last updated: 2026-08-28

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 (Server Edition, amd64 only). Four AI tools come preinstalled: CMai (the CMai API — one key, every model) plus Claude Code, Gemini CLI and Kimi CLI; every user works in their own workspace, isolated with rootless podman. The path from install to your first `cmai` command is four steps: 1) Install — boot the ISO; the unattended install takes the whole disk. 2) Wizard — use the address and code on the console card to enter your licence, CMai API key and admin account in a browser. 3) SSH — `ssh <admin>@<ip>` lands straight in the workspace. 4) Publish — projects go live on an automatic subdomain of the server's domain, with TLS.

## Requirements

| Component | Recommended to start | Note |
|---|---|---|
| CPU | 8 vCPU | amd64 (x86-64) only |
| RAM | 32 GB | add up the quotas you plan to give each user |
| Disk | 500 GB NVMe | the install takes the whole disk |
| Network | a static IP is recommended | outbound HTTPS to license.cmaios.net is required for licensing |
| Firmware | BIOS or UEFI | both are supported |

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

## Downloading the ISO

The current ISO is at https://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

CAREFUL: the install is unattended and erases the WHOLE of the selected disk. Do not run it on a machine that holds data.

- 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:

    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 https://app.cmai.tr/customer/keys. This single key is written into every user's workspace (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. To see the setup code later, type `cmai setup code` on the console; if the card has scrolled away, `cmai banner` redraws it.

## 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. 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 (https://cmai.tr) is the enterprise AI platform built by CMApps: 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 entered 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 the 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 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: https://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).

Environment variables ready in every workspace (any OpenAI-compatible tool reaches the CMai API with no extra configuration):

| Variable | Value |
|---|---|
| CMAI_API_KEY | the cm-… key entered in the wizard |
| CMAI_BASE_URL | https://gw.cmai.tr/v1 |
| CMAI_MODEL | cmai-pro (the CMai CLI default; cmai-balanced, cmai-fast and cmai-vision are selectable) |
| OPENAI_API_KEY | the same as CMAI_API_KEY (a mirror for OpenAI-compatible tools) |
| OPENAI_BASE_URL | the same as CMAI_BASE_URL |

API endpoints: POST /v1/chat/completions (SSE streaming, tool/function calling, text · image · PDF · audio · video input), /v1/embeddings, /v1/files, /v1/models. Authentication: `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: https://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"}]}'

The other AI tools (with your own account): Claude Code · Gemini CLI · Kimi CLI are installed in every workspace and start with `claude`, `gemini` and `kimi`; on first run you sign in with your own provider account or API key (BYOK). Claude Code needs Anthropic's own API format, so it does not run through the CMai API. CMai API usage is drawn from your CMai credits at app.cmai.tr; no AI usage fee is included in the CMai OS licence.

Host commands: commands on the host (the admin CLI 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"

The same commands can also be typed 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.

| Command | What it does |
|---|---|
| cmai license status | Licence status: plan, user count, validity, connection state, device id |
| cmai license activate <key> | Binds the key to this device; the console route to unlocking a locked server |
| cmai license renew | Syncs with the licence service immediately |
| cmai license deactivate | Unbinds the key from this device so it can be used on another server |
| cmai user add <name> [--cpus N] [--mem MB] [--pids N] [--ssh-key "…"] [--password-stdin] [--no-start] | A new sandboxed user, with quotas and a login method |
| cmai user start\|stop\|rm <name> | Starts or stops a user's workspace, or deletes the user |
| cmai user shell <name> [command…] | Opens a shell (or runs one command) in a user's workspace |
| cmai update check | Checks the selected channel for a new release |
| cmai update apply | Applies the update |
| cmai update channel [stable\|beta\|nightly] | Shows or changes the update channel |
| cmai doctor | Checks services, networking, the licence and the workspaces |
| cmai banner | Redraws the console card |
| cmai setup code | Shows the first-boot setup code |

## Licensing

CMai OS uses online activation: the key binds to a device once, and the server verifies its licence online.

| Event | Behaviour |
|---|---|
| Activation | In the wizard, or with `cmai license activate`. The key binds to this server's device id |
| Connectivity | The server needs outbound HTTPS to license.cmaios.net. Short outages change nothing; if the connection cannot be made for a long time the server enters lock mode and reopens automatically when connectivity returns |
| Lock mode | SSH, workspaces and published projects stop. No data is deleted. The console card shows the reason and the panel address |
| Unlocking | Local admin panel at https://<ip>:8443 → enter a new key, or on the console `cmai license activate <key>`. No reinstall is needed |
| Moving servers | `cmai license deactivate` on the old server (or "Release device" at portal.cmaios.com), then activate with the same key on the new one |

Plans and pricing (monthly, USD, excl. VAT; AI usage fees not included): Trial free (14 days, 1 user, 1 server); Solo $29/mo (1 user, 1 server); Team $99/mo (5 users included, $19/mo per extra user, up to 20 users, 1 server); Enterprise quoted, from $499/mo per server (20+ users, multiple servers, priority support). Current list: https://cmaios.com/en/#planlar. For a key or a quote: isgelistirme.ortaklik@cmapps.com.tr. Customer portal (https://portal.cmaios.com/): licences, bound devices, releasing a device, renewal requests; login is passwordless, by email link.

## Admin panel

The address the wizard ran on becomes the admin panel after installation: https://<ip>:8443. You sign in with the admin account 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"; "CMai API key" (change it; it is written into every workspace and the CMai CLI runs on it); a connection summary (SSH line, admin name, 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); the defaults are strict and every measure below is active out of the box:

| Layer | Measure |
|---|---|
| Signing | Licence responses and update packages are Ed25519-signed; no update whose signature does not verify is applied, and no licence response is accepted |
| Transport | All traffic (the licence service, the update channel, the panel, published projects) is encrypted with TLS 1.2+/1.3; there is no plain HTTP |
| SSH | Key-based access; when an SSH key is entered or added from the panel, password login switches off automatically; SSH stays closed until setup is finished |
| Firewall | nftables, default-deny: only 22 (SSH), 8443 (panel) and 80/443 (published projects) are open |
| Brute force | fail2ban blocks repeated SSH and panel attempts |
| Isolation | Every user runs in their own rootless podman workspace: read-only rootfs, cap-drop ALL, no-new-privileges, CPU/RAM/disk/process quotas |
| Keys | The licence key, the CMai API key and the device id are kept on the server only, in root-only files; no code or data leaves the machine |

Full-disk encryption, FIPS certification and hardware-backed key storage (mandatory TPM) are not in this release. Security reports: https://cmaios.com/.well-known/security.txt

## Troubleshooting

- SSH "Permission denied (publickey)": the server only accepts key-based logins and does not recognise the key you offered. Use the right key (`ssh -i ~/.ssh/id_ed25519 admin@<ip>`); if you chose a password in the wizard, `ssh -o PubkeyAuthentication=no admin@<ip>`; to add another user's key, `sudo cmai user add <name> --ssh-key "…"`.
- "Your workspace is being prepared": on the first login the container is created; if the workspace image is still being prepared this can take a few minutes. Watch it with `ssh admin@<ip> "sudo journalctl -u cmai-workspace-<name> -f"`. If it hangs, `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. 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`; if it is a connectivity problem, `cmai license renew`.

## Releases and updates

Version format: `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

- I lost the setup code: type `cmai setup code` on the console; if the card has scrolled away, `cmai banner`.
- Changing the licence key later: "New licence key" in the panel, or `sudo cmai license activate CMAI-…`; no reinstall is needed.
- The server locked — is my data gone? No; in lock mode the services stop and the disk is left untouched.
- The same key on two servers? Up to your licence's server limit; when the limit is reached, release the old device.
- Can users reach the host? No; everyone is in their own rootless podman workspace, and host commands are for the admin only, through sudo.
- Where do I get a CMai API key? https://app.cmai.tr/customer/keys (cm-…); entered at the AI step of the wizard, changed later from the https://<ip>:8443 panel; written into every workspace as CMAI_API_KEY.
- What is the CMai CLI? @cmapps/cmai-cli — the CMai coding agent that lives in your terminal; preinstalled in every workspace and connected automatically with the server's CMai API key. `cmai` (or `cmai code`) opens an interactive session, `cmai -p "…"` runs a one-shot command, `cmai mcp add …` adds an MCP server, and a CMAI.md at the project root gives standing instructions; automatic memory, skills and sub-agents; settings persist under /workspace/.cmai; models cmai-pro / balanced / fast / vision.
- Do I pay separately for AI usage? Yes; CMai API usage is drawn from your CMai credits at app.cmai.tr, and Claude Code · Gemini CLI · Kimi CLI run on their own providers' accounts; none of it is included in the licence.
- Ports: from outside, 22 (SSH), 8443 for the panel if you want it remotely, and 80/443 for published projects; outbound HTTPS from the server to license.cmaios.net.
- Backups: user data lives under /workspace; take snapshots or rsync at server level, or have users push to remote repositories with git.

## Glossary

- Workspace: a user's own rootless podman container; SSH logins land in it; HOME=/workspace is persistent.
- User count: the number of users the licence allows.
- 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; strengthened by TPM where one is present.
- Verification: the server verifying its licence through license.cmaios.net.
- Lock mode: the state where SSH, workspaces and published projects stop while a licence is invalid, and data is preserved.
- Channel: the update stream — stable, beta, nightly.
- Console card: the status card on the physical console (panel address, setup code, SSH line, licence summary).
- Setup code: the one-time 8-character code (XXXX-XXXX) needed to open the wizard.
- 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).