Quick start

Install a published IO Gateway release or build it from source, then open the operator dashboard, add upstream credentials, and verify that a model request reaches a provider account.

Choose an install path

• Published release Recommended for a desktop or server. It does not require Rust, Docker, or administrator access.
• Build from source Use this when developing IO Gateway or when your operating system is not covered by a published release.
• Provider credential Prepare at least one upstream account before testing real model calls.

Install a published release

The release installers select the native archive for the current computer, verify the downloaded archive against the release SHA256SUMS file, and keep an existing configuration and credential directory intact during upgrades.

Linux and macOS

bash -c 'set -o pipefail; curl -fsSL https://github.com/giofahreza/io-gateway/releases/latest/download/install.sh | sh'

The Bash wrapper preserves a failed curl exit status instead of treating an empty download as a successful install. In an interactive terminal, the Unix installer reads setup answers from /dev/tty, not from the downloaded script stream, so this curl | sh command can still ask its first-run questions safely.

Windows PowerShell

irm https://github.com/giofahreza/io-gateway/releases/latest/download/install.ps1 | iex

Use --version vX.Y.Z on Linux or macOS, or -Version vX.Y.Z in PowerShell, to install a particular release.

Supported release platforms

Other CPU families and 32-bit systems are not currently published as release assets.

Choose first-run setup

• Installs per user No sudo or Administrator prompt is needed by default.
• Choose a local port The first question chooses a TCP port from 1 through 65535 (default 8319). The installer preflights 127.0.0.1:<port>: an occupied interactive choice is asked again, while an explicit or unattended occupied port fails before a new config is created. The generated config stays localhost-only, creates auths/, and generates a private client API key.
• Choose the terminal client Decide whether to install the optional iogw management client and TUI beside the gateway binary.
• Choose autostart at sign-in Enable a systemd user service on Linux, a LaunchAgent on macOS, or a per-user Scheduled Task on Windows. This is a persistent next-sign-in choice, not an immediate launch.
• Choose whether to start now Start the gateway immediately after installation, independently of autostart. Choose this for a one-off local background process even when sign-in autostart is off, or decline it while enabling the next-sign-in service.

These questions apply only when a configuration does not already exist. Upgrades preserve the existing configuration, credential directory, and chosen listen port.

Automate an install

Use explicit flags when there is no terminal or when setup must be repeatable. Unix accepts --port, --with-iogw / --without-iogw, --autostart / --no-autostart, --start-now / --no-start, and --interactive / --non-interactive. PowerShell accepts -Port, -InstallIogw / -NoIogw, -AutoStart / -NoAutoStart, -StartNow / -NoStart, and -Interactive / -NonInteractive.

IO_GATEWAY_PORT=9444 \
IO_GATEWAY_INSTALL_IOGW=no \
IO_GATEWAY_AUTOSTART=no \
IO_GATEWAY_START_NOW=no \
IO_GATEWAY_INTERACTIVE=no \
bash -c 'set -o pipefail; curl -fsSL https://github.com/giofahreza/io-gateway/releases/latest/download/install.sh | sh'

The same cross-platform environment variables are available with values auto, yes, or no where applicable: IO_GATEWAY_INSTALL_IOGW, IO_GATEWAY_AUTOSTART, IO_GATEWAY_START_NOW, and IO_GATEWAY_INTERACTIVE; IO_GATEWAY_PORT selects the port. Explicit command-line choices take precedence. --start-now / -StartNow starts the gateway immediately without changing autostart; --no-start / -NoStart skips that launch while preserving an existing service or task. Combine --autostart --no-start for a next-sign-in-only service, or --no-autostart --start-now for a one-off local background process.

Finish setup

1. 1
   Open the local dashboard.

   If you chose Start now, visit http://127.0.0.1:<selected-port>/ after the gateway becomes healthy (the default is http://127.0.0.1:8319/). Otherwise, use the printed command to start it now or sign in again when autostart is enabled.

2. 2
   Review configuration.

   Use the configuration reference to set listen, proxy_api_key, auth_dir, and dashboard authentication for the intended environment.

3. 3
   Add a provider account.

   Use the provider account workflow before sending client traffic.

Verify

# Replace 8319 if you chose another first-run port.
curl http://127.0.0.1:8319/health
curl http://127.0.0.1:8319/ready

After the health checks pass, use Test API from the dashboard to send a short prompt through one model route.

Build from source

For development or an unsupported platform, work from a repository checkout with Rust installed.

cargo build --release
cp config.example.json config.json
# Edit config.json before exposing the gateway.
./target/release/io-gateway --config ./config.json

--config PATH takes precedence over IO_GATEWAY_CONFIG. When a selected configuration uses a relative auth_dir, IO Gateway resolves it from that configuration file's directory rather than the current working directory.

Next steps

• Secure dashboard access Configure admin auth before exposing the service.
• Create managed API keys Replace broad shared-key access with provider/account scopes, per-request input caps, and optional input-token budgets.
• Plan routing Use priority routing or custom models when traffic should prefer specific accounts.