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.

Desktop executable or server command?

If you want to…	Use
Connect an Electron window to a local or remote server	Open the AirCode Ø desktop app
Run the embedded local server and use it from Electron	Open the desktop app and choose Run on this machine
Run a server without an Electron window	Open a terminal and run `aircode serve`

The desktop executable is not a supported --serve entry point: it always opens Electron. The aircode command uses the runtime and server payload installed with the desktop app, but starts a separate foreground process. See Desktop operating modes for the complete lifecycle summary.

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`
`--password <value>`	generated or configured	Access password for this process. Convenient but visible in shell history and potentially process inspection. Env: `AIRCODE_AUTH_PASSWORD`; JSON: `authPassword`
`--password-file <file>`	none	Read the access password from a private file
`--no-password`	off	Disable authentication explicitly; use only on an intentionally trusted interface
`-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.

On first run AirCode Ø generates a password, stores it in the selected configuration file, and prints it once. --password is available when complete command-line provisioning is required, but its value can be exposed through process inspection and shell history. Prefer --password-file, a protected config file, or a securely supplied AIRCODE_AUTH_PASSWORD. Disabling auth must be explicit with --no-password.

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.