Skip to main content

Install X4

X4 is currently a private repo-local tool. The root package builds the x4 binary from src/cli.ts.

Local Developer Install​

pnpm install
pnpm build
ln -sfn "$PWD/dist/cli.js" ~/.local/bin/x4
x4 doctor

The repository also includes install helpers:

scripts/install.sh
scripts/install-devbox.sh
scripts/install-codex-plugin.sh
scripts/install-editor-extension.sh

Use the scripts when provisioning a devbox or refreshing adapters; use the manual commands when working directly inside the repo.

Host Prerequisites​

X4 assumes a Linux host with:

  • Git
  • Node.js and pnpm
  • Bubblewrap and user namespace support for Codex sandboxing
  • Tailscale for private preview and remote node connectivity
  • Docker for local sandbox profiles that require containers
  • Azure CLI when the environment uses Azure-backed services
  • optional GitHub CLI or GitHub App credentials for GitHub mutations

Run:

x4 doctor host
x4 doctor devbox

Control And Worker Install​

Control nodes and testbox workers use separate scripts:

scripts/install-control.sh
scripts/install-worker.sh
scripts/install-control-poller.sh

Control nodes keep authoritative job and lease state under /srv/x4/control. Workers keep execution workspaces under /srv/x4/workspaces and artifacts under /srv/x4/artifacts.

Mastra Orchestrator Install​

The Mastra orchestrator lives in apps/mastra-orchestrator/.

cd apps/mastra-orchestrator
npm install
npm run typecheck
npm test -- tests/shared/unit/code-assist
npm run build

The deployed service uses an env file and systemd service outside the repo. Never commit real env values.