Configure ipa-hub through the environment of the process doing the work: your CLI command, foreground server, or application using the library. Explicit command options take precedence over their environment defaults.
Storage and server port
| Variable | Purpose and default |
|---|---|
IPA_HUB_HOME | Data directory for downloads, app records, credentials, and server state. Defaults to ~/.ipa-hub. Override with --data-dir or the library’s dataDir option. |
IPA_HUB_PORT | TCP port for HTTP and UDP port for WebRTC Direct, used by serve, service install, and independent app installations. Overrides the saved port in server/config.json; otherwise the default is 19464. Override with --port. Accepts integers from 1 to 65535. |
export IPA_HUB_HOME=~/Library/ipa-hub
export IPA_HUB_PORT=19465
ipa-hub serveUse the same data directory for commands that should share a server, app records, and credentials. Changing IPA_HUB_HOME selects a different directory; it does not move existing files.
Independent installations discover and embed all usable machine destinations, even without a running server. They save the listener settings so a later server can use the same port. A running server embeds its active port. In library code, startServer and installService use the same precedence: explicit port, IPA_HUB_PORT, saved port, then 19464. The hub’s publicURL adds a destination and sets the port used for the embedded update URLs.
Source authentication
These variables are optional; no tokens are configured by default.
| Variable | Purpose |
|---|---|
GITHUB_TOKEN | Access token for https://github.com and https://api.github.com. It is not sent to custom GitHub instances. |
GITLAB_TOKEN | Access token for https://gitlab.com. It is not sent to custom GitLab instances. |
IPA_HUB_TOKENS | JSON object mapping exact HTTPS origins to access tokens; defaults to {}. Use it for custom GitHub/GitLab instances or other HTTPS download hosts. |
export GITHUB_TOKEN='your-github-token'
export GITLAB_TOKEN='your-gitlab-token'
export IPA_HUB_TOKENS='{"https://github.company.example":"your-token","https://downloads.example.com":"another-token"}'Origins include the scheme and host, plus a port when it is not the default. They do not include a repository or file path. An entry for https://downloads.example.com does not apply to its subdomains or to https://downloads.example.com:8443.
Authentication is selected in this order:
- The installation’s explicit
--access-tokenor libraryaccessTokenoption. - An exact-origin entry in
IPA_HUB_TOKENS. GITHUB_TOKENorGITLAB_TOKENfor the public hosts listed above.
An empty string in IPA_HUB_TOKENS disables environment authentication for that origin. IPA_HUB_TOKENS must be a valid JSON object even when an explicit token is supplied. Tokens require HTTPS and are sent as bearer credentials. Redirects do not carry authorization to a different origin.
Only an explicitly supplied per-install token is saved for later updates and signature refreshes. Environment tokens remain process configuration: future operations need them in the process that performs the network request. When an installation is delegated to a running server, it uses the server’s environment; a token exported only in the client’s terminal is not forwarded. See private downloads for per-install authentication.
Background service
service install saves the resolved data directory and port as launch arguments, and captures the current PATH. Changing IPA_HUB_HOME, IPA_HUB_PORT, or PATH afterward does not reconfigure an installed service; run service install again with the intended settings.
The LaunchAgent does not copy source-authentication or terminal-color variables from your shell. Use --access-token when installing a private app to retain its token for server-side updates, or run ipa-hub serve in a process with the required environment.
Terminal and executable settings
| Variable | Behavior |
|---|---|
NO_COLOR | Disables CLI colors when present, including when set to an empty string. |
NODE_DISABLE_COLORS | Disables CLI colors when present, including when set to an empty string. |
FORCE_COLOR | 0 disables colors. Other values do not force colors in ipa-hub; output must still be a terminal that reports color support. |
TERM | dumb disables colors and uses numbered selections instead of arrow-key menus. Other values participate in the runtime’s terminal capability detection. |
PATH | Search path for executables invoked by name, including npm. Service installation saves its current value, falling back to /usr/bin:/bin:/usr/sbin:/sbin if unset. |
NO_COLOR=1 ipa-hub device lsipa-hub only uses colors for terminal output with color support. Piped output stays uncolored. It inherits the process environment for child commands but sets LC_ALL=C so their output can be parsed consistently. Provisioning builds use a private TMPDIR inside their temporary workspace; TMPDIR does not configure ipa-hub’s temporary-directory location.
Building and testing the repository
These variables are for contributors. They do not configure an installed ipa-hub server.
| Variable | Purpose and default |
|---|---|
WEBSITE_BASE | Base path for the website’s Vite build, generated documentation URLs, and website browser tests. Defaults to /. Use leading and trailing slashes. |
WEBAPP_BASE | Base path for the webapp’s Vite assets and service-worker cache URLs. Defaults to /app/ and must stay within /app/ to keep the website outside the worker's scope. This does not change the server’s hosted-manager URL or the Pages packaging destination. |
DOCS_PACKAGE_VERSION | Version displayed in generated documentation and the website toolbar. Defaults to the version in package.json. The release workflow sets it to the published version. |
IPA_HUB_TEST_CHROMIUM | Chromium executable for website screenshots, website browser tests, and offline-webapp tests. Defaults to /usr/bin/chromium. |
IPA_HUB_DEV_ALLOW_NON_MACOS | Development-only platform override. Set exactly 1 to enable CLI commands and the real library implementation on another OS. Unset by default. It does not emulate Xcode, signing, or device access. |
CI | CI=true skips Git-hook installation in the repository’s prepare script. Unset by default. |
IPA_HUB_TEST_CHROMIUM='/Applications/Chromium.app/Contents/MacOS/Chromium' npm run test:websiteWithout the development override, every CLI command on a non-macOS system exits with code 1 and a macOS-only error. Programmatic getIpaHub() calls warn once per instance and return an inactive instance: device, team, app, and release lists are empty; other operations reject with the macOS-only error. These instances do not create a data directory or contact a server. The library’s warn callback can receive the warning instead of the console.