​
Install

Already followed Getting Started? You’re all set — this page is for alternative install methods, platform-specific instructions, and maintenance.

​
System requirements

On Windows, we strongly recommend running TraseAI under WSL2.

​
Install methods

From source is currently the only supported install method. npm packages and installer scripts are not yet available.
For VPS/cloud hosts, avoid third-party “1-click” marketplace images when possible. Prefer a clean base OS image (for example Ubuntu LTS), then install TraseAI from source.

From source

1

Clone and build

Clone the TraseAI repo and build:
git clone https://github.com/mk-rcp/traseai.git
cd traseai
pnpm install
pnpm build
2

Link the CLI (optional)

Make the traseai command available globally:
pnpm link --global
Alternatively, skip the link and run commands via pnpm traseai ... from inside the repo.
3

Run onboarding

pnpm traseai onboard --install-daemon
Or if you linked globally:
traseai onboard --install-daemon
For deeper development workflows, see Setup.

​
Other install methods

Docker

Containerized or headless deployments.

Podman

Rootless container: run setup-podman.sh once, then the launch script.

Nix

Declarative install via Nix.

Ansible

Automated fleet provisioning.

Bun

CLI-only usage via the Bun runtime.

​
After install

Verify everything is working: 
traseai doctor         # check for config issues
traseai status         # gateway status
traseai dashboard      # open the browser UI
If you need custom runtime paths, use:
  • TRASEAI_HOME for home-directory based internal paths
  • TRASEAI_STATE_DIR for mutable state location
  • TRASEAI_CONFIG_PATH for config file location
See Environment vars for precedence and full details.

​
Troubleshooting: traseai not found

Quick diagnosis:
node -v
npm -v
npm prefix -g
echo "$PATH"
If $(npm prefix -g)/bin (macOS/Linux) or $(npm prefix -g) (Windows) is not in your $PATH, your shell can’t find global npm binaries (including traseai).Fix — add it to your shell startup file (~/.zshrc or ~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"
On Windows, add the output of npm prefix -g to your PATH.Then open a new terminal (or rehash in zsh / hash -r in bash).

​
Update / uninstall

Updating

Keep TraseAI up to date.

Migrating

Move to a new machine.

Uninstall

Remove TraseAI completely.