How setup works
- Deployment: SaaS, On-premises
Every way of setting up AITrax, the CodeTogether AI tracker, runs the same underlying commands. Knowing this makes setup problems easier to reason about, because there is only one thing to inspect regardless of how setup was started.
The native commands own all configuration
aitrax setup and aitrax uninstall perform all setup-related changes. Every other surface is a
thin delegator that ends up calling them.
The following table lists what each entry point does:
| Entry point | What it does | What it does not do |
|---|---|---|
| Bootstrap script | Detects your platform, downloads aitrax, runs aitrax setup system | Write or merge configuration itself |
| The portal's Onboarding page | On SaaS, accepts the activation code issued from Settings > Activation Codes — the value that connects a workstation to that deployment, valid for seven days by default — and renders the copy-paste command with it filled in. On-premises, renders the workstation setup link and the per-IDE plugin downloads | Configure anything, or issue the code itself |
| IDE plugins | Detect that setup is missing, prompt, then call aitrax setup system | Write configuration |
| Update service | Serves bootstrap scripts and binaries, read-only | Apply setup logic |
The practical consequence: if setup fails, the entry point is rarely the cause. Inspect the native command and its output.
The scope
Setup writes user-level settings on the workstation. That is the System scope, and it is the only scope there is — there is no repository-level or project-level setup to configure.
aitrax setup check reports the status of that scope, and repairs two known configuration
defects if it finds them — a missing Git fallback path, and a corrupted Codex config.toml. It
is the correct first step for any setup question.
How the binary is obtained
The bootstrap resolves your base URL, detects your operating system and architecture, and downloads the matching build into the tracker directory. Setup then runs from a throwaway copy of that binary, which avoids the file-lock failure that occurs when setup rewrites the binary it was launched from.
A small core binary handles daily tracking work. Setup escalates to a larger build that owns setup, activation-code redemption, and diagnostics.
Related
- Files and locations — where the binaries and settings live.
- AITrax CLI reference — the commands described here.