LanguageEnglish

Install

Web app for iPhone, iPad and Android

The AirCode Ø web app is the permanent no-store client. It is served by your own running instance, not packaged in the signed download channel, so it remains available independently of Google Play, the App Store and TestFlight.

  1. Start an AirCode Ø instance and give it a stable HTTPS address. See Quickstart and Remote Access.
  2. Open the dedicated Web app setup, enter the HTTPS instance origin, and select Open install page. The same setup is also available on Download. The website validates the value locally and never submits or stores it.
  3. Sign in on the instance. Chromium exposes its own install prompt; iPhone and iPad use the guided Share → Add to Home Screen flow.
  4. Launch the installed icon. Enable Push notifications only if you want closed-app alerts; iOS and iPadOS offer that control only from the Home Screen web app.

Installation is origin-scoped. An HTTP LAN address is not a complete mobile PWA target, and changing the HTTPS origin requires a separate installation and may require authentication again. The web app updates from the instance through its service worker; it is not an APK, IPA, or Store package.

The web app carries the responsive core workspace. Native mobile remains the better choice when you need secure in-app server switching, encrypted managed offline files, reliable bounded background tasks, native sharing/scanning, haptics, notification-channel priority, or operating-system deep links.

Linux server

The installer is published only when the release manifest, checksums and signing checks have passed. Confirm that the server build is marked available on the download page before running the command.

curl -fsSL https://dl.aircodezero.com/install.sh | bash

This command installs the latest stable release. The installer options below select a beta or an exact version instead.

The installer:

  1. detects your platform (linux-x64, linux-arm64),
  2. downloads the release tarball and verifies its sha256 checksum and Ed25519 signature,
  3. installs to ~/.aircode/versions/<version> with a ~/.aircode/current symlink,
  4. links aircode into ~/.local/bin,
  5. checks system dependencies (git, tmux) and tells you exactly what to install if something is missing.

No root required. Everything lives in your home directory. Re-running the installer repairs or updates the installation. If ~/.local/bin is not in the current shell’s PATH, the final instructions use the immediately runnable ~/.aircode/current/bin/aircode path and also show the optional PATH export.

Then start the instance from the directory that should contain the selectable projects:

cd /srv/workspaces
aircode start

On Linux, aircode start creates the path-scoped configuration, chooses a free port, generates and prints an access password, starts a systemd user service, and enables recovery after crashes and reboots. It also attempts to enable systemd linger and prints one exact repair command if the host requires administrator approval. No hand-written unit file is needed.

If this installation still owns the historical aircode.service unit, the first aircode start safely removes that unit before creating the path-scoped service, so both servers cannot compete for the same port. Units owned by a different checkout or installation are never modified.

Installer options: --channel beta (the default channel is stable), --version x.y.z, and --no-modify-path. The historical --service option remains compatible with the old single-instance unit; new installations should use aircode start.

System requirements

Requirement Notes
Linux x64 / arm64 Ubuntu 22.04+, Debian 12+, Fedora (recent) — glibc
git, tmux sudo apt-get install -y git tmux
Agent CLIs Installed and authenticated with your accounts; use the tested versions in Quickstart for version-sensitive TUI integrations
systemd required for persistent aircode start; not required for foreground aircode serve

The Node.js runtime is embedded — no system Node required.

Docker

The public aircodezero/aircode image runs the same published Linux server package that install.sh installs. Node.js, the web client, Claude Code, Codex, Grok Build and Kimi Code are bundled. It is published for linux/amd64 and linux/arm64 under the stable and beta tags and exact version tags such as 0.1.30.

Start it on any Docker host with one command:

docker run -d --name aircode --restart unless-stopped --stop-timeout 30 -p 7860:7860 -v aircode-home:/home/aircode aircodezero/aircode:stable

Docker Compose

The website serves a ready-to-use compose.yaml. Save it in a directory of its own and start it from there:

curl -fsSLO https://aircodezero.com/docker/compose.yaml
docker compose up -d

Deploy on Hostinger

Deploy on Hostinger The guided deployment prepares your browser’s access before opening Hostinger.

  1. Choose a VPS with Ubuntu 24.04 and Docker (x86-64). KVM 2 (2 vCPU, 8 GB RAM) suits a small test. Review the price and renewal before paying.
  2. Docker Manager opens the prepared recipe. Select Deploy, then use the project’s HTTPS Open link.
  3. Continue in the browser that started deployment, confirm the instance address and choose its password. Keep this browser’s site data until setup is complete.

First access

These steps cover manual Docker (docker run or the portable Compose). Hostinger uses the HTTPS setup above.

Open http://<server-address>:7860. On first start, the container prints a generated password once in its logs:

docker logs aircode

To choose the password instead, set the AIRCODE_AUTH_PASSWORD environment variable when you create the container. You can change the password later in the app’s settings.

Private HTTPS address

In AirCode Ø, open Settings → Remote access and select Sign in to connect your AirCode Ø account. The server then gets its private HTTPS address through the Relay:

https://<name>.tunnel.aircodezero.com

The Relay connection is outbound only, so there is no port to open. See Remote access for details.

Data and updates

Projects, provider sign-ins, conversations and settings all live in the aircode-home volume. Deleting the volume deletes them.

To update, pull the new image and recreate the container. With Docker Compose, run this next to compose.yaml:

docker compose pull && docker compose up -d

With docker run, pull the image, stop and remove the container, then run the same docker run command again:

docker pull aircodezero/aircode:stable
docker stop aircode && docker rm aircode

The container never starts a release older than one its volume already ran. If the server process stops inside the container, the container restarts it, and agent sessions survive that restart.

macOS

Desktop app (recommended): download the .dmg from the download page. It embeds the full server (local sessions) and connects to remote servers too.

Headless / CLI: the same one-liner as Linux works on macOS 13+ (darwin-arm64, darwin-x64). Install tmux via Homebrew first, then use aircode serve; persistent aircode start currently requires Linux systemd.

Windows

Install the desktop app from the download page. Local sessions run natively on Windows through ConPTY. The installer embeds the server and its Node.js runtime, so WSL, a Linux distribution, and a system Node installation are not required. It also adds aircode to the current user’s PATH, allowing the embedded server to run from PowerShell or Command Prompt. Open a new terminal after setup and see the Windows command-line reference. The app can also connect to remote AirCode Ø servers.

Desktop operating modes

Goal Start Result
Remote client only Open AirCode Ø and choose Connect to a server without configuring Local The Electron window loads the selected remote AirCode Ø server
Local client + server Open AirCode Ø, choose a projects folder, then choose Run on this machine Electron starts and manages the embedded native server, then loads its workspace
Server only Run aircode serve --projects-root "D:\Projects" in PowerShell or Command Prompt The bundled server runs in the foreground without an Electron window

Do not launch the desktop executable with --serve: it opens Electron and does not provide a server-only mode. Use the aircode command installed in PATH for a terminal-only server.

After Local has been configured, normal desktop startup ensures that the embedded server is running, even while a window is connected to a remote server. The desktop-managed server listens only on 127.0.0.1. To connect from another device, use Remote access or start a CLI server with an explicit private-network bind address.

On Windows, closing every desktop window leaves AirCode Ø and its embedded server running in the notification area. Choose Quit from that icon to stop the embedded server. A CLI server is a separate process and can coexist on a different port; see Desktop app coexistence.

Heavy optional components

Nothing big is downloaded implicitly:

aircode browser install   # pinned Chromium for the agent browser
aircode doctor browser    # verify it

Knowledge remains lexical until you explicitly install a local embeddings model from its settings. The model is then verified and used offline; indexing never triggers an implicit model download.