Windows command line

The AirCode Ø Windows setup installs an aircode command for PowerShell and Command Prompt. It uses the Node.js runtime and ConPTY support already embedded in the desktop application; WSL and a system Node.js installation are not required.

Open a new terminal after installing or updating AirCode Ø so it receives the updated user PATH, then verify the command:

aircode version
aircode serve --help

The installer resolves the command relative to its own installation directory, so choosing a custom directory in setup is supported.

Start a server

serve is the default command, so these forms are equivalent:

aircode serve --projects-root "D:\Projects"
aircode --projects-root "D:\Projects"

The server runs in the foreground and writes logs to that terminal. Press Ctrl+C to stop it cleanly. Each projects root gets its own isolated runtime state and session namespace. When the preferred port is already used by another root, AirCode Ø selects the next available port automatically.

Serve options

Option	Default	Purpose and equivalent setting
`--projects-root <dir>`	current directory	Root whose subfolders AirCode Ø presents as projects. The directory must already exist. Env: `AIRCODE_PROJECTS_ROOT`; JSON: `projectsRoot`
`--host <address>`	Tailscale IP, otherwise `127.0.0.1`	Network interface on which the HTTP server listens. Env: `AIRCODE_HOST`; JSON: `host`
`--port <number>`	`7860`	HTTP port from 1 to 65535. An explicit busy port fails instead of silently changing. Env: `AIRCODE_PORT`; JSON: `port`
`--public-url <url>`	none	Public HTTP(S) base URL used in links and notifications. Env: `AIRCODE_PUBLIC_URL`; JSON: `publicUrl`
`--config <file>`	user config file	Alternate JSON configuration file. Env: `AIRCODE_CONFIG`
`--state-dir <dir>`	user state directory	Alternate runtime-state directory. Env: `AIRCODE_STATE_DIR`
`-h`, `--help`	—	Show command help without starting the server

The standard Windows config file is %USERPROFILE%\.config\aircode\config.json; runtime state defaults to root-specific directories beneath %USERPROFILE%\.local\state\aircode\instances.

Paths containing spaces must be quoted. Both --option value and --option=value are accepted. Command-line options take precedence over environment variables, which take precedence over config.json, then defaults.

There is deliberately no --password argument because command arguments can be exposed through process inspection and shell history. On first run AirCode Ø generates a password, stores it in the selected configuration file, and prints it once. For unattended provisioning, set AIRCODE_AUTH_PASSWORD securely in the process environment or place authPassword in a protected configuration file.

Examples

Multiple roots at the same time

Open one terminal in the first root:

cd "$HOME\Desktop"
aircode

Then open another terminal in a different root:

cd "$HOME\Documents"
aircode

If Tailscale assigned 100.84.12.30 to the computer, the two banners can report http://100.84.12.30:7860 and http://100.84.12.30:7861. The instances do not share runtime state or sessions. Running aircode again from a root that is already active reports its existing URL instead of starting a duplicate.

Local machine only

aircode serve `
  --projects-root "D:\Projects" `
  --host 127.0.0.1 `
  --port 7860

Open http://127.0.0.1:7860.

Tailscale or a private VPN

Bind the exact VPN address assigned to the Windows machine:

aircode serve `
  --projects-root "D:\Projects" `
  --host 100.84.12.30 `
  --port 7860

Other devices on the same private network can then open http://100.84.12.30:7860. Prefer an exact VPN address over 0.0.0.0.

Local network

aircode serve `
  --projects-root "D:\Projects" `
  --host 192.168.1.25 `
  --port 7860

Windows Firewall may ask whether to allow the connection. Only allow the network profiles you intend to use.

Reverse proxy or tunnel URL

aircode serve `
  --projects-root "D:\Projects" `
  --host 127.0.0.1 `
  --port 7860 `
  --public-url "https://aircode.example.com"

--public-url only tells AirCode Ø which address to place in generated links. It does not open a firewall port, start a reverse proxy, or create a tunnel. Use Remote access for the built-in outbound tunnel, Tailscale, or private-network guidance.

Separate configuration and state

aircode serve `
  --projects-root "D:\Projects" `
  --config "D:\AirCodeData\config.json" `
  --state-dir "D:\AirCodeData\state"

If another terminal needs to run a lifecycle command against this instance, set the same state directory first:

$env:AIRCODE_STATE_DIR = "D:\AirCodeData\state"
aircode status
aircode stop

Desktop app coexistence

The foreground CLI server and the local server managed by the desktop window are separate processes. aircode status and aircode stop only target the foreground CLI server; they do not report or control the desktop-managed server. Before reusing the same host and port, quit AirCode Ø from its notification-area icon, not only by closing its window. Alternatively, give the CLI server another port.

Starting from a terminal exposes the AirCode Ø web application and its authenticated API. It does not turn the projects directory into a public file share: file access remains scoped to projects beneath projectsRoot and is enforced by the server.

Additional settings

Agent executable paths, session limits, browser controls, knowledge, orchestration, notifications, and token optimization remain available through environment variables and config.json. See Configuration for the complete configuration precedence and common settings.