AITM — Docker Installation Guide

Requirements

• Docker Desktop (Windows, macOS) or Docker Engine + Compose plugin (Linux) — version 24 or newer.
• On Windows, Docker Desktop must be set to use the WSL2 / desktop-linux backend, not Hyper-V-only or Windows containers.
• At least 8 GB RAM; 32 GB recommended if pipeline tasks, builds, and test suites run concurrently.
• At least 100 GB free disk — the image plus named volumes, per-project worktrees, artifacts, and logs grow over time.
• Port 3333 free on the host is convenient but not required — the automatic installer (--auto/-Auto) detects an occupied port and picks a free one itself (see step 2).
• The release package: the extracted aitm-release-v<version> folder, containing the installer scripts at its root and a docker/ subfolder with the image tarball and compose files, obtained from your AITM Release Manager output.

Quick install

Run the installer from the root of the extracted release package. In fully-automatic mode (--auto / -Auto) it verifies/installs Docker, creates docker/.env, generates a strong AITM_ADMIN_TOKEN, auto-picks a free port if 3333 is taken, verifies package authenticity, loads the image, starts the container, and waits for it to report healthy — no prompts.

bash install-docker.sh --auto

bash install-docker.sh --auto

install-auto.bat

Drop --auto/-Auto to run the same script interactively — it prompts for the admin token and port instead of deciding automatically. Prefer to understand every step, or want to configure things by hand? Follow the manual walkthrough below, or jump to Advanced / For advanced users for the full .env reference.

01 Copy the release to the target machine

Copy the entire extracted release folder — not just the image tarball — to the machine that will run AITM. You need all of these together:

# Example: copy over SSH to a remote host
scp -r aitm-release-v2.5.1/* user@target-host:/opt/aitm-install/

02 Configure .env

Inside the docker/ folder, copy .env.example to .env, then edit the values. Everything else in the file has a safe default. The automatic installer does this step for you.

For the full list of environment variables, see Advanced / For advanced users below.

03 Load the image and start the container

# From inside the docker/ folder:

# Load the Docker image
docker load -i aitm-release-v2.5.1.tar.gz

# Start the container
docker compose up -d

# Watch it come up
docker compose logs -f

Look for this line in the logs — it means the server is accepting connections:

[AITM] URL : http://localhost:3333

04 First run in the browser

1. Open http://<host-ip>:3333 (or http://localhost:3333 if running locally).
2. Go to Settings → License and activate your license key, or start a free 3-day trial (see Trial Mode below).
3. Go to Settings → Providers and enter your AI provider API key (Anthropic / OpenAI / Gemini). Until a license is activated or trial started, all /api/* requests return HTTP 423 — this is expected.

Trial mode (3 days)

AITM includes a built-in 3-day trial mode that requires no license key. During trial, you have access to:

Starting your trial

1. On first login, go to Settings → License.
2. Click Start free 3-day trial.
3. The trial starts immediately and expires after 72 hours.
4. No email or account registration required — device activation is local only.

Managing the service

Updating to a new release

Copy the new release package over the old install folder and re-run the same installer (bash install-docker.sh --auto / install-auto.bat / install-docker.ps1 -Auto). It automatically detects an existing install and switches to upgrade mode: it prints Upgrading AITM <old> -> <new>, keeps your existing docker/.env (admin token and port unchanged), reuses the existing named volumes, and only replaces the image and recreates the container.

The installer refuses to install a package older than the currently deployed version (compared via AITM_VERSION in docker/.env, or by querying GET /api/version on the running container) — pass --force-downgrade (bash) / -ForceDowngrade (PowerShell) to override.

To upgrade by hand instead: load the new image (docker load -i aitm-release-v<new-version>.tar.gz, replacing the local aitm:release tag) and run docker compose up -d again to recreate the container. Existing data volumes are untouched — license activation and task history carry over.

Security & Isolation

AITM runs entirely inside its Docker container, isolated from the host system. The AI agent cannot reach files or processes on the host machine outside the volumes and paths you explicitly mount into the container.

• Host requirement: Docker Engine (or Docker Desktop) must already be installed on the host — the installer verifies/installs it but does not replace a proper Docker setup.
• Supported host OS: AITM is designed and tested to run on Ubuntu Linux. Other platforms (macOS, Windows via WSL2) may work through Docker Desktop but are not the primary target.
• Only the three named volumes described in step 3 (aitm-data, aitm-home, aitm-worktrees) and the port you expose are shared between the container and the host — everything else stays inside the container boundary.

Advanced / For advanced users

The quick install at the top of this page covers everything most installs need. The table below documents every docker/.env variable for advanced or manual configuration.

AI provider API keys and the AITM license key are not set in .env — you enter those inside the app after first start (see step 4).

Troubleshooting

Docker Desktop won't come up on Windows

If docker info fails with failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine, the backend service isn't running yet — launching the tray icon alone doesn't guarantee it's initialized.

Get-Service com.docker.service
# If Stopped:
Start-Service com.docker.service
# Then launch Docker Desktop and wait ~30-60s, checking:
docker info

Container exits immediately with Cannot find module 'bindings'

This is a packaging defect in some early builds: the image is missing a runtime dependency that the encrypted database driver needs. Check docker logs <container> for MODULE_NOT_FOUND with bindings in the require stack. Fixed upstream — make sure you're on the latest release. If you're stuck on an affected build, the missing packages are node_modules/bindings and node_modules/file-uri-to-path, which need to sit alongside node_modules/better-sqlite3-multiple-ciphers inside the image.

Container exits with NODE_MODULE_VERSION mismatch

A message like was compiled against a different Node.js version using NODE_MODULE_VERSION 137. This version of Node.js requires NODE_MODULE_VERSION 108 means the native database driver was compiled against a different Node.js ABI than the one bundled in the binary. This is a build-pipeline defect, not something to fix per-install — it will need a corrected release build.

Container shows unhealthy in docker ps, but the app works

Some builds ship without the internal aitm-ctl helper binary the container's healthcheck calls. If http://<host>:3333 loads fine and curl -H "X-AITM-Admin-Token: <token>" http://localhost:3333/api/admin/health returns {"status":"healthy",...}, the app itself is fine — only the Docker-reported health status is wrong. Safe to ignore until a corrected release; it does not affect restart: unless-stopped behavior.

License activation returns an error

License activation happens entirely in the UI and talks to AITM's built-in license server automatically. If activation fails, check that the container has outbound internet access and that your license key is correct.

Port 3333 already in use

Set AITM_PORT=<free-port> in .env and re-run docker compose up -d.

Trial won't start — says device is already activated

Each device can only activate one trial at a time. If your trial has expired and you're within a 24-hour cooldown period, you must wait before starting a new one. To check your device's activation state, go to Settings → License → Device Info.