Get

Remote access

AirCode Ø is built to be driven from anywhere while the application, projects, terminals and agents keep running on your own machine. Never expose it unauthenticated to the public internet.

Built-in Remote Access

The desktop app and server include an outbound-only tunnel. You do not need to open a router port or configure dynamic DNS:

  1. Open Remote access from the broadcast icon in the activity bar.
  2. Open Settings and select AirCode Ø relay.
  3. Return to Remote access and enable the tunnel.
  4. Open the generated HTTPS URL, or select Generate pairing QR code and scan it from Add server → Scan QR code on the mobile app.

Your AirCode Ø password still protects the server, and the application, projects and sessions remain on the host machine. The tunnel refuses to start if no password is configured. A pairing QR never contains that password: it contains a random capability that expires after five minutes and stops working after its first successful scan. The server then gives that phone its own revocable token.

If Windows Security blocks the desktop tunnel

AirCode Ø bundles frpc.exe, the client that creates the outbound tunnel. A Windows Security policy may classify proxy software as a potentially unwanted application and refuse to start it. When AirCode Ø detects that refusal, Remote access shows The tunnel client could not start with View instructions and Retry actions.

  1. Select View instructions, then Open Windows Security.
  2. Open Virus & threat protection → Protection history and expand the latest potentially unwanted app entry.
  3. Verify that the affected file belongs to the AirCode Ø installation you trust and that its path ends with \resources\payload\vendor\frpc\frpc.exe. A matching detection may be named PUA:Win32/FRProxy.
  4. Only when both the installation and path match, choose Allow on device.
  5. Return to AirCode Ø and select Retry.

If the detection name or file path differs, leave the item blocked and inspect it separately. Never disable Windows Security or add an exclusion for the whole AirCode Ø installation folder. Microsoft explains the available actions in its Protection history guidance.

Command-line setup on a Linux server

Authorize the managed Relay account before requesting it for an instance:

aircode login
aircode whoami
aircode start --projects-root /srv/workspaces --relay managed --generate-password

The device authorization is shared by all AirCode Ø instances owned by the same Unix user. Each instance keeps its own port, password, public slug, tunnel identity, and enabled state. First service boot completes enrollment and the tunnel reconnects with the server after crashes and reboots.

Managed Relay refuses to start when the account is signed out, the account has no active entitlement, or the instance has no password. aircode logout removes the shared machine credential. Existing managed connections can remain alive until their current lease expires, so stop or switch those instances to private mode before signing out when immediate disconnection matters.

Other launch choices are explicit:

aircode start --relay private
aircode start --relay custom --relay-url https://relay.example.com \
  --relay-enrollment-token-file /run/secrets/aircode-relay-enrollment
aircode start --relay off

private selects VPN/private-network-only mode. off closes the public tunnel without forgetting a previously selected managed or custom transport.

Managed-relay trust boundary

The current managed relay terminates TLS before forwarding authenticated traffic to your AirCode Ø host. Relay operators can therefore technically access traffic while it passes through the relay, even though application and session data are not stored there as part of the normal service. End-to-end encryption that prevents relay inspection is not yet available.

Use Private network only with Tailscale or another VPN, or operate a custom relay, when that trust boundary does not meet your requirements.

Fast preview and Shared browser

The Browser screen offers two different transports:

  • Fast preview is the default for a localhost development URL. The page, assets, live reload and HMR WebSockets render directly on the viewing device; Chromium does not run on the server. With Remote Access enabled, AirCode Ø creates a revocable preview origin through the relay. Opening it once exchanges the access link for an HttpOnly cookie. You can add a per-preview password as a second layer; the private link is still required, the password is stored only as a local hash, and failed attempts are rate-limited.
  • Shared browser runs Chromium on the server and streams the same interactive session to people and agents. Choose it when an agent needs browser control, diagnostics, screenshots or traces.

Closing a Fast preview revokes its relay origin. Preview links are access capabilities even when a password is enabled: do not publish them.

Tailscale or your own VPN

For peer-to-peer access without the AirCode Ø relay, open Remote access → Settings and select Private network only. AirCode Ø then opens no public tunnel.

Install Tailscale on the server and your devices. AirCode Ø detects and binds the tailnet IP automatically; open http://<tailnet-ip>:7860 from another device. tailscale serve can add HTTPS with a real certificate:

sudo tailscale serve --bg "http://$(tailscale ip -4):7860"

The first run may print an admin-console link to enable Serve/HTTPS on your tailnet (a one-time, one-click switch).

WireGuard, ZeroTier or an SSH tunnel (ssh -L 7860:localhost:7860 server) work the same way.

Custom relay

Organizations can run the three-container Caddy + FRP + registry appliance from the AirCode Ø source tree. It keeps application and project data on employee hosts, closes new-machine enrollment by default, and gives every instance an independent tunnel identity.

On the Relay host:

cd infra/relay
./aircode-relay init \
  --control-domain relay.example.com \
  --tunnel-domain tunnel.example.com \
  --tls-mode provided
# Add a certificate covering relay.example.com and *.tunnel.example.com:
#   tls/fullchain.pem
#   tls/privkey.pem
./aircode-relay up
./aircode-relay doctor
./aircode-relay enrollment create --expires 15m --uses 1 --label alice-laptop

Put the displayed one-time value in a mode-0600 file on the AirCode Ø host, then use the custom Relay command shown above. AirCode Ø consumes and removes the pending token after successful enrollment. FRPS requires TLS, and the host pins the appliance’s internal CA and server name from the authenticated HTTPS enrollment response.

Many employees can share one Relay. That does not turn one AirCode Ø instance into a safe multi-user server: use one Unix account, container, or VM and one instance per employee until same-instance roles and execution isolation are implemented.

The desktop and mobile apps

Add a connection manually with the server URL + password, or generate a single-use QR code under Settings → Security & access → Pair a phone. Connections and paired-device tokens are stored in the platform’s secure credential storage. The desktop app shows the active server in the bottom-left status indicator — click it to switch or add servers (local or remote).

The native mobile app is only a client of an already reachable server address. It does not configure the built-in tunnel, manage an AirCode Ø account for the managed Relay, or enable and disable public exposure. Those host-side controls remain in the Web and Desktop server surfaces. The mobile address may be a LAN or VPN address, a user-operated reverse proxy, or a public Relay URL. A current QR imports that address and exchanges its one-time capability for a token owned by that phone; older address-only QR codes still fall back to password entry. Scanning a QR does not activate or require a Relay. Paired phones can be reviewed and revoked individually under Security & access on web, responsive web, or native mobile.

Pairing uses HTTPS by default. When the server is already reachable through an HTTP LAN or private-VPN address, enable Allow pairing on this local connection before generating the QR. That choice applies only to the next five-minute code and turns itself off after generation.

Install the web app from the HTTPS instance

The store-free AirCode Ø client is installed from the exact HTTPS origin that serves your instance. Once the managed Relay, a custom Relay, or your own trusted HTTPS reverse proxy is active:

  1. open the HTTPS instance address on the phone or tablet and sign in;
  2. choose Install web app from More or Settings → Web app;
  3. accept the Chromium install prompt, or follow the iPhone/iPad guide for Share → Add to Home Screen;
  4. launch the installed icon, then enable Push notifications explicitly if you want closed-app alerts.

On iPhone and iPad, Web Push is offered only after the web app is launched from its Home Screen icon. The browser and operating system remain responsible for installation and permission prompts. One installed web app belongs to one origin; moving an instance to a different origin means installing that new origin and signing in again.

You can start the same handoff from the dedicated Web app setup or from Download. The marketing site validates the address locally, discards credentials, paths, queries and fragments, and opens only /?pwa-install=1 on the resulting HTTPS origin. It does not receive or retain the instance address.

The responsive web app covers the core workspace, sessions, attention requests, terminal, files, Git, Browser/Applications, Focus Plans, Prompt Queue, Scheduled Tasks, settings and notification-device management. Native mobile still has deeper operating-system integration: encrypted local storage, secure multi-server profiles, bounded background work, native file/camera/share flows, haptics, notification channels and aircode:// links. Browser storage can be evicted, background execution is not guaranteed, and iPhone/iPad installation is manual.

Firewalls

The built-in tunnel requires no inbound port. It makes outbound connections to the relay over HTTPS and FRP. Private-network mode opens no additional connection; your VPN determines reachability. Fast previews use authenticated ephemeral ports on the same interface as the AirCode Ø server, so a restrictive host firewall must allow traffic from the private network to those ports.

For a Docker sandbox session, this route still ends at the host AirCode Ø control plane. Terminal traffic then crosses the Docker API to the worker. The tunnel does not automatically carry worker egress and does not publish development ports from the container.