# Deployment guide for IT teams

**Codelux AI** — Windows, macOS, Linux. Written against release 3.6.1 (28 September 2026).
Everything below describes what the app does today. Items marked **Not yet** do not exist;
do not plan a rollout that depends on them.

---

## 1. What you are deploying

| Item | Fact |
|---|---|
| Artifact | One ZIP per platform containing one executable: `codelux.exe` (Windows) or `codelux` (Linux, macOS). No installer, no runtime dependencies. |
| Platforms | Windows x64 · Linux x86_64 · Linux ARM64 · macOS Apple Silicon · macOS Intel. macOS is the newest port and the least field-tested. |
| Process | One daemon per machine. It serves the local dashboard, the MCP endpoint (`http://localhost:8766/mcp`), the REST API and the CLI's backend. |
| Listening | `127.0.0.1` and `[::1]` only, port **8766** by default. Nothing listens on external interfaces. |
| Outbound | `https://codelux.ai` (443) — licence, account, project list, signed UI bundle. `rt.codelux.ai:4222` over TLS — Team plan only. The dashboard page in the user's browser loads its code editor and diagram renderer from `cdn.jsdelivr.net`. |
| Code signing | **Not yet.** No Windows Authenticode signature, no Apple Developer ID / notarization. See the platform notes below for first-launch warnings. |
| Packages | **Not yet**: no MSI, PKG, DEB, RPM, winget, Homebrew or apt repository. |

### Personal builds vs the public Free build

| Build | Where it comes from | Identity |
|---|---|---|
| Free (public) | `codelux.ai/download` — the same binary for everybody | The user creates the account or signs in **inside the app**. |
| Multi / Team (paid) | Each user's own Console on codelux.ai (My account › Downloads › App) | The build is **personal**: it carries that account's licence credentials and binds to the first machine it is authorised on. |

Consequence for mass deployment: **one image for all paid users does not exist yet.** Each
paid user downloads their own build (or IT downloads it while signed in as that user), and
each device is authorised by the user signing in. Team members covered by a seat download the
**Team build** from their Console (My account › Downloads); the Free build can read a team project but cannot write
to it. A generic enterprise binary with SSO sign-in and pre-provisioned activation is **not
yet** available (SSO sign-in on the website exists from 3.7; the binary and the device
activation are still per user).

### One Codelux per machine

A machine-wide lock allows one running daemon per machine, whatever the account. On shared
hosts (terminal servers, pooled VDI) only one user can run it at a time. Across machines the
server arbitrates: the latest sign-in wins and the older machine stops at its next licence
check.

### Connectivity requirement

The app checks its licence every 60 seconds. After three consecutive failed checks (about 15
seconds) it goes offline and refuses writes until the next good check; the signed offline
grace is capped at 2 minutes. An offline or air-gapped mode is **not yet** available. Allow
the outbound endpoints above in your firewall and proxy.

---

## 2. Install

### 2.1 Windows

```powershell
# Elevated PowerShell (or your software-distribution agent running as SYSTEM).
# .\codelux.zip stands for the ZIP you downloaded.
$dest = "C:\Program Files\Codelux"
New-Item -ItemType Directory -Force $dest | Out-Null
Expand-Archive -Path .\codelux.zip -DestinationPath $dest -Force
Unblock-File "$dest\codelux.exe"          # remove the downloaded-from-internet mark
& "$dest\codelux.exe" install-service      # registers and starts the "codelux" service
```

- `install-service` creates the service **codelux** (display name "Codelux"), start type
  **Automatic**, command line `codelux.exe start --service`, and starts it. If an existing
  service is found it is stopped and recreated. Run it from an elevated context; from a
  non-elevated console it relaunches itself through UAC.
- The service runs as **LocalSystem**. Micro-apps (the app's optional user programs) refuse
  to start under the service, so no model-written program ever runs as SYSTEM.
- SmartScreen: the binary is unsigned and every personal build has its own hash, so a first
  interactive launch may show "Windows protected your PC" (More info → Run anyway).
  `Unblock-File` avoids it for deployed copies.
- For a per-user, non-service setup, place the binary in a user-writable folder and run
  `codelux start` (for example from a logon script); it stays in the foreground.

### 2.2 Linux

```bash
sudo install -m 0755 codelux /usr/local/bin/codelux
sudo codelux install-service     # writes /etc/systemd/system/codelux.service, enables, starts
```

- The generated unit: `Type=simple`, `ExecStart=/usr/local/bin/codelux start --service`,
  `Restart=on-failure`, `RestartSec=5s`, `WantedBy=multi-user.target`, `After=network.target`.
- Micro-apps (optional user programs started from the dashboard) are refused under the
  Windows service but **not yet** under the systemd unit, where they would run as root. On a
  Linux service install, do not use micro-apps; run `codelux start` in the user's session if
  you need them.
- The unit has no `User=` line: it runs as **root**. Running the service as a dedicated
  unprivileged user (your own unit with `User=`) is possible in principle but **not yet
  tested or supported**; note that the state directory then follows that user's home.
- If a ZIP tool drops the executable bit, `chmod +x codelux`.
- Without a service: `codelux start` in the user's session.

### 2.3 macOS

```bash
mkdir -p ~/bin && cp codelux ~/bin/ && chmod +x ~/bin/codelux
xattr -d com.apple.quarantine ~/bin/codelux   # the build is not notarized
~/bin/codelux start
```

- **No service mode on macOS yet:** `install-service` answers "service install not supported
  on this OS". To start it at login you can write your own LaunchAgent that runs
  `codelux start`; Codelux does not ship or test one.
- Without the `xattr` step, Gatekeeper blocks the first launch (right-click → Open also works
  interactively). PKG / MDM deployment is **not yet** supported.

### 2.4 First start and device authorisation

1. Open `http://localhost:8766` on the machine.
2. Free build: create the account or sign in (email code). Paid build: sign in with the
   account the build belongs to; the device is then authorised.
3. Accept the Terms if asked (the app is gated until the current version is accepted).
4. Add projects from the Console (My account › Account › Your projects) or the app; the project list lives on
   the account, not in a local file.

Unattended activation (no user sign-in) is **not yet** available.

### 2.5 Connect the AI agents

| Agent | How |
|---|---|
| Claude Code | `claude plugin marketplace add codeluxai/codelux` then `claude plugin install codelux@codelux`. The hooks need `bash` and `curl` (on Windows, Git Bash). |
| Cursor, VS Code, Windsurf, JetBrains, Zed, other MCP clients | Add the MCP server URL `http://localhost:8766/mcp` (change the port if you changed it). |
| Codex, Gemini CLI | Hook configuration files ship with the plugin (`hooks/`); experimental. |
| Scripts, CI | REST API on the same port, or the `codelux` CLI. |

---

## 3. Configuration

### 3.1 Where things live

| Data | Windows | Linux | macOS |
|---|---|---|---|
| State directory (credentials, local config, team keys, error log) | `%ProgramData%\Codelux` | `~/.config/codelux` (`$XDG_CONFIG_HOME/codelux`); for the root service `/root/.config/codelux` | `~/Library/Application Support/codelux` |
| Per-project data | `<project>\.codelux\` | `<project>/.codelux/` | `<project>/.codelux/` |

- `codelux where` prints the state directory in use.
- The state directory is created with restricted permissions (Windows: SYSTEM, Administrators
  and the installing user, inheritance removed; Unix: 0700). A directory owned by someone else
  is refused and the app falls back to a per-user location (`%AppData%\codelux` on Windows).
- Files in it are sealed to the machine (`codelux.tok`, `.usr`, `.cred`, `.kp`, `.teams`,
  provider secrets) and do not open on another machine. `codelux.cfg` is
  plain JSON. `codelux-error.log` records persistence errors (rotated at 1 MB).
- Per-project data: `index.db`, `knowledge.db` (memories, notes, timeline), `sessions.db`,
  `writes.db`, `tasks.db`, `graph.db`, `logs.db` — **plaintext** database files — and
  `settings.json`. For projects shared through a synced folder (Team "Shared folder" mode) the
  databases move to `<state directory>/projects/<hash>/` so two machines never lock the same
  file; `settings.json` stays in the project.
- Use full-disk encryption on developer machines (BitLocker, LUKS, FileVault): the app does
  not encrypt the project databases.

### 3.2 `codelux.cfg`

The only local configuration file. Two keys:

```json
{
  "port": "8766",
  "ui_lang": "en"
}
```

| Key | Meaning |
|---|---|
| `port` | Port of the dashboard, MCP and REST API (1–65535, digits only). Invalid values are ignored with a warning. |
| `ui_lang` | Dashboard language. |

- Created on first start with the default port. UTF-8 with or without BOM is accepted; a file
  that cannot be parsed is left untouched and the session runs on 8766.
- Restart the service after editing. The MCP URL of every agent must use the new port.
- You can pre-seed this file in the state directory before the first start.
- Everything else (projects, plan, teams) comes from the account on the server.

### 3.3 Per-project `settings.json`

`<project>/.codelux/settings.json`: `include` (sub-paths to index), `exclude` (directories,
files, globs), `share_mode` (Team: shared folder or git clones) and the verification-gate
options. Editable from the dashboard; can be committed with the project.

### 3.4 Environment variables

| Variable | Effect in a release build |
|---|---|
| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Honoured by the HTTPS calls to codelux.ai (Go standard behaviour). |
| any `CODELUX_*` | **None** changes the release app. Development overrides (realtime URL, hardware id, UI directory) are compiled out of release builds. `CODELUX_APP_PORT` is set **by** the app for its micro-apps; it is not the daemon's port. |

- Configuration through environment variables is **not yet** available.
- The Team realtime connection (`rt.codelux.ai:4222`, TLS) is a direct TCP connection; going
  through an HTTP proxy is **not yet** supported.

---

## 4. Updates

- **No automatic update yet.** The licence server's signed answer tells the app the latest
  version; the dashboard shows when an update is available.
- The dashboard UI (the web page) updates itself from a signed bundle without replacing the
  binary.
- To update the binary: download the new build (the user's Console, My account › Downloads, for paid plans, the
  download page for Free), then:

```powershell
# Windows
codelux stop                                   # stops the service (elevates if needed)
Expand-Archive .\codelux.zip "C:\Program Files\Codelux" -Force
Unblock-File "C:\Program Files\Codelux\codelux.exe"
Start-Service codelux
```

```bash
# Linux
sudo codelux stop
sudo install -m 0755 codelux /usr/local/bin/codelux
sudo systemctl start codelux
```

- Replace the binary at the **same path**: the service points to the path it was installed
  from.
- A newly downloaded paid build carries fresh credentials; the stored device token is bound to
  the binary that wrote it, so the new binary uses its own automatically. If the app reports a
  token mismatch, run `codelux reset-token` and sign in again.
- Local data (state directory, `.codelux` folders) is kept across updates.

---

## 5. Uninstall

```powershell
# Windows
codelux uninstall-service                  # stops and deletes the service
Remove-Item -Recurse -Force "C:\Program Files\Codelux"
Remove-Item -Recurse -Force "$env:ProgramData\Codelux"   # credentials, team keys, config
```

```bash
# Linux
sudo codelux uninstall-service             # stops, disables, removes the unit, daemon-reload
sudo rm /usr/local/bin/codelux
rm -rf ~/.config/codelux                   # and /root/.config/codelux for the root service
```

Also, as needed:

| What | How |
|---|---|
| Project data | Delete `<project>/.codelux/` in each project (memories, notes, timeline, index). |
| Agent context blocks | Remove the block between `<!-- codelux:start -->` and `<!-- codelux:end -->` in `AGENTS.md` / `CLAUDE.md`. |
| Claude Code plugin | `claude plugin uninstall codelux@codelux`; remove the MCP server entry from other agents. |
| Seat / account | Remove the member from the team (owner or admin), or delete the account from the Console (My account › Account › Delete account). |

**Before removing a Team member's machine:** the team key and the team's decrypted history are
on it. Deleting the state directory and the `.codelux` folders removes them from that machine;
rotate the team key from the owner's app so later events are not readable with the old key.

---

## 6. Command reference (service and operations)

| Command | What it does |
|---|---|
| `codelux start` | Runs the daemon in the foreground (dashboard + MCP + API). |
| `codelux start --service` | Same, in service mode (used by the service definition). |
| `codelux install-service` | Installs and starts the service (Windows SCM / systemd). Elevates if needed. |
| `codelux uninstall-service` | Stops and removes the service. |
| `codelux stop` | Stops the running service. |
| `codelux where` | Prints the state directory. |
| `codelux reset-token` | Deletes the stored device token (fixes "token mismatch"). |
| `codelux help` | Version-matched reference of the CLI and API. |

---

## 7. Gaps summary

| Need | Status |
|---|---|
| MSI / PKG / DEB / RPM packages, winget / Homebrew | Not yet |
| Code signing (Authenticode) and Apple notarization | Not yet |
| One generic paid binary, silent pre-activated install | Not yet |
| macOS service (launchd) | Not yet |
| Service under a non-root / non-SYSTEM account | Not yet (tested and supported only as LocalSystem / root) |
| Micro-apps blocked under the Linux service | Not yet (blocked under the Windows service only) |
| Automatic binary updates | Not yet |
| Configuration through environment variables / MDM profiles | Not yet |
| Realtime through an HTTP proxy | Not yet |
| Offline / air-gapped operation | Not yet |
| Several users on one machine (VDI, terminal server) | Not supported (one Codelux per machine) |
| On-premise hub (`codelux-hub`: integrations, realtime, encrypted archive, admin console) | Yes, included with Team and Enterprise (4.1) |
| SSO / SCIM for the account | From 3.7 (website sign-in; the app signs in through the website) |

Questions: **hello@codelux.ai**.