Install BOS API with one command

Install BOS API on Linux or macOS. Start an existing checkout without Nginx and optionally access it by IP and port.

Installation & operations guideUpdated Oct 26, 2026

Choose a deployment method

If the complete BOS API application source is already uploaded or cloned, use --local to build and start it in place. Add --public for direct access by server IP and port. Go serves both the frontend and API; no Nginx installation or static directory is required.

Without a checkout, use the archive-download installer below. For manual Compose configuration and builds, use the dedicated Docker Compose guide. All methods share the default bosapi-stack containers and volumes; do not create a second default instance on the same Docker daemon.

Prerequisites

Run commands on the Linux server or Mac that will host BOS API, with Docker ready first. --local can reuse private configuration in the source directory. Preserve the original configuration and keys when data already exists.

ItemRequirement
Operating systemLinux amd64 / arm64, or macOS on Intel / Apple silicon. Start Docker Desktop or another local Docker runtime on Mac and run the installer without sudo.
Required toolsPrepare Docker, Compose v2 with up --wait support, Buildx, Bash, OpenSSL, curl, and tar. The entry installer checks dependencies without installing Docker. Ubuntu 26.04 can use the application repository’s separate deploy/install-docker.sh.
Docker environmentUse a local Unix socket with working docker info access. Add Compose or Buildx separately if an existing Docker installation lacks them.
Network & resourcesBuilds still require image registries, npm/pnpm, Go modules, and upstream services. --local skips only the GitHub source archive download. Allow enough memory and disk for the first build.
PortsThe app defaults to port 18080 on all IPv4 interfaces with --public, otherwise loopback by default. MySQL stays at 127.0.0.1:13306 and Redis has no published port. Automatic HTTPS also needs 80 / 443.
  • Host installations of Go, Node.js, MySQL, and Redis are unnecessary; Docker manages the build and data services.
  • The Compose project name is fixed to bosapi-stack. Use one default installation per Docker daemon; do not install concurrently in different directories.

Existing source: start and update without Nginx

Upload or clone the complete BOS API application source, then enter its root containing install.sh, frontend/, backend/, and deploy/. Use the bos-api application repository, not the boss-api-protal website repository that hosts this page.

Initial deployment and updates use the same command below. The first run generates configuration, builds, and starts the stack. For an update, prepare the new source and rerun in the original directory to reuse configuration and data. --local does not fetch new code.

Configured automaticallyResult
Frontend & APISaves BOS_WEB_DELIVERY=go so the app serves the website and API together. Nginx, Python static publication, and Caddy are unnecessary.
Public binding--public saves BOSAPI_BIND_IP=0.0.0.0. --port selects the application host port without changing MySQL or Redis exposure.
Configuration & startupGenerates random passwords and keys when configuration is missing, or reuses deploy/stack.env. Builds through stack.sh up --source, waits for health, and checks the login page.
Server: access by IP and port without Nginx
./install.sh --local --public --port 18080

Builds the source in place without downloading it again. First check docker info, docker compose version, and docker buildx version. On Linux, use sudo only if Docker access requires it.

Mac or host-only access: omit --public
./install.sh --local --port 18080

Do not use sudo on macOS. After a new installation, open http://localhost:18080/login on that machine. Add --public for LAN access if the network permits it.

  • Before public access, allow inbound TCP 18080 in the server’s attached cloud security group and host firewall, or the selected custom port. Open http://SERVER_IP:18080/login using the server’s public IP. This mode serves HTTP without obtaining an HTTPS certificate.
  • --local requires a saved installer with its complete supporting source. It cannot be piped from curl or combined with --dir or --ref. --public cannot be combined with --domain or used on an existing installer-managed HTTPS deployment.
  • Private configuration remains at deploy/stack.env in the checkout. Reruns retain passwords, keys, mounts, and updater settings while rebuilding the current source. --local explicitly selects source deployment; the existing stack.sh workflow removes an old image pin only after successful startup.
  • Explicitly repeated ports and initial administrator emails must match existing configuration. Omitting --public does not disable a saved public binding. To return to loopback, edit BOSAPI_BIND_IP to 127.0.0.1 in the existing configuration and apply it with stack.sh start.

Existing source: update and rerun the same command

Use these examples for an instance installed with --local --public --port 18080, from its original bos-api application directory on the server. First back up deploy/stack.env, the database, and other persistent data, and review migrations in the target release.

Git checkout: inspect the current branch and local changes
git status --short
git branch --show-current
git rev-parse HEAD

Preserve and resolve local changes first. The pull command below assumes a tracking branch that you intend to update. For a pinned tag or commit, select the target revision first.

Git checkout: pull, then rebuild and deploy
git pull --ff-only && ./install.sh --local --public --port 18080

--ff-only stops when a fast-forward is unavailable, and && prevents deployment after a failed pull. Running the installer alone only rebuilds the current source.

Uploaded source or selected revision: rerun once source is ready
./install.sh --local --public --port 18080

Sync the complete new source into the original directory, preserving deploy/stack.env, custom data directories, and enabled markers. Uploaded directories may have no .git metadata and do not need git pull.

Check after updating
./deploy/stack.sh status
curl --noproxy "*" -fsS --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/health/ready

Also verify browser sign-in, a model request, and usage records. Use the actual port if customized.

  • Reruns preserve existing passwords, keys, and data mounts, rebuild the frontend and backend, and start the stack. Updates may briefly interrupt service. No uninstall, preliminary down, or Nginx configuration is required.
  • Use ./deploy/stack.sh start when you only need to start existing images. Source updates require a rebuild; start alone does not deploy new code.
  • For host-only or HTTPS deployments, retain the original installer flags instead of copying --public. Preserve data volumes and original keys. For archive installations, see the backup and upgrade section.

Download source: run the installer

Sign in to the server with a sudo-capable account and run the command below. It downloads source from main and installs to /opt/bosapi.

Run on the deployment server
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh

Omit sudo when already logged in as root. curl must be available before this command can download the installer.

  • The script downloads the source and generates independent random passwords, a JWT signing key, and a data encryption key in deploy/stack.env with mode 600.
  • Docker Compose builds and starts the app, MySQL, and Redis. The app serves the bundled frontend with BOS_WEB_DELIVERY=go.
  • The installer waits for container health and checks /health/ready and /login before displaying the login URL and initial administrator credentials. The first build may take several minutes or longer.
  • If downloading returns 404, confirm that the repository and main/install.sh are anonymously accessible and that main contains the installer and supporting deployment files.

Connect and sign in

With --public, allow the selected port and open http://SERVER_IP:18080/login directly, without Nginx or an SSH tunnel. With --domain, use https://YOUR_DOMAIN/login.

A new installation without --public or --domain listens only on loopback. Open http://127.0.0.1:18080/login on the host, or use the SSH tunnel below when the application runs on a remote server.

Run on your workstation
ssh -N -L 18080:127.0.0.1:18080 deploy-user@server.example.com

Replace deploy-user and server.example.com with your SSH user and server address. Keep the tunnel running and open http://127.0.0.1:18080/login in your workstation browser.

  • The default administrator email is admin@bosapi.local. The script generates a random password and displays it after the first successful installation. Enroll an MFA authenticator on first login.
  • Read BOS_ADMIN_EMAIL and BOS_ADMIN_PASSWORD privately from deploy/stack.env in the actual deployment directory: the source checkout for --local, or /opt/bosapi for the default root archive installation. After a portal password change, the initial password in this file is no longer current.
  • Public HTTP requires BOSAPI_BIND_IP=0.0.0.0, the correct port mapping, and access through the security group and host firewall. Changing BOSAPI_PORT or opening a security group alone does not switch a default loopback binding to public access.

Optional: enable HTTPS during installation

For a domain with HTTPS, select --domain during the first installation; it cannot be combined with --public. With an existing checkout, run ./install.sh --local --domain api.example.com, or use the download command below. Point the domain’s A / AAAA records to this server, ensure ports 80 / 443 are free, and allow them through the host firewall and cloud security group.

Domain & automatic certificates
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh -s -- \
  --domain api.example.com \
  --admin-email owner@example.com

Replace the example domain and email. --domain accepts a hostname without https://, a path, or a port.

  • The installer adds Caddy to obtain and renew certificates and redirect HTTP to HTTPS. The login URL is https://api.example.com/login.
  • If 1Panel, Nginx, or another service already owns ports 80 / 443, install without --domain and configure HTTPS in that proxy. Forward to 127.0.0.1:18080 only when the proxy can reach the host loopback interface; 127.0.0.1 inside a container refers to that container.
  • The installer verifies the local HTTPS certificate and readiness endpoint. Check public DNS and firewall reachability from an external network afterward. Rerunning the installer cannot add or change a domain on an existing installation.

Installer options

For an existing checkout, pass options directly after ./install.sh. For the download workflow, pass them after sudo sh -s --. --local requires a saved script and cannot be piped from a download. Omit sudo on macOS and replace example paths and email addresses.

OptionDefaultPurpose
--localDisabledBuild the complete application source beside the script in place, reusing its configuration and serving the frontend through Go. Cannot be combined with --dir or --ref.
--publicDisabledSave an all-interface IPv4 application binding for HTTP access by IP and port. Does not install Nginx or change database ports. Cannot be combined with --domain.
--dir PATH/opt/bosapiNew absolute installation path. Non-root users without sudo default to $HOME/.local/share/bosapi.
--ref REFmainChoose a branch, tag, or commit containing the installation files. For reproducibility, download the entry script from the same tag or commit.
--domain DOMAINDisabledEnable public HTTPS through Caddy on first installation.
--port PORT18080Application host port (1–65535), on loopback by default or all IPv4 interfaces with --public. An explicitly repeated port must match existing configuration.
--admin-email EMAILadmin@bosapi.localInitial administrator email.
--help—Show usage and options.
Custom directory & port
curl -fsSL https://raw.githubusercontent.com/secure-typex/bos-api/main/install.sh | sudo sh -s -- \
  --dir /srv/bosapi \
  --port 19090 \
  --admin-email owner@example.com

If you customize the directory or port, adjust later commands, login URLs, and SSH tunnel ports accordingly.

Components & persistent data

These are Compose logical volume names; default Docker volume names carry the bosapi-stack_ prefix. Copying the source directory does not copy data from Docker volumes.

Component / fileAccess & persistence
appGo gateway and compiled React portal, default 127.0.0.1:18080 → container 8081, or 0.0.0.0:18080 with --public, without Nginx. Gateway data persists in gateway_data.
MySQL 8.4127.0.0.1:13306 → container 3306; database data persists in mysql_data.
Redis 7.4Container-network access only; AOF and other data persist in redis_data.
deploy/stack.envPrivate configuration, initial credentials, and encryption keys; back it up with the data and keep it out of source control.
Caddy (optional)Public ports 80 / 443; certificates and configuration persist in caddy_data / caddy_config. deploy/https.enabled enables the HTTPS overlay.

Verify and configure model access

Check status from the actual deployment directory: the application checkout for --local, or /opt/bosapi for a default root archive installation. Readiness should report data.status equal to ok. Also verify the login page and portal in the actual browser. Use sudo if required by a Linux root installation, never on macOS.

Check service status from the deployment directory
./deploy/stack.sh status
curl --noproxy "*" -fsS --connect-timeout 5 --max-time 20 http://127.0.0.1:18080/health/ready
Public mode: check from your workstation without a proxy
curl --noproxy "*" -I --connect-timeout 5 --max-time 20 http://SERVER_IP:18080/login

Replace SERVER_IP and any custom port. A 200 response here still needs browser verification; browser proxy extensions can operate independently of system proxy settings.

  • After MFA enrollment, configure your own upstream accounts or API keys, channels, and models. Deployment does not supply model credits or upstream access.
  • Create an organization and assign its available channels and models, then create an organization gateway key for your application.
  • Make an authorized request to an available model and check the response, request record, and usage. Passing health checks does not establish that upstream inference is configured.

Routine operations

Run these commands from the actual deployment directory as the same Docker user used for installation. Add sudo for a Linux root installation when needed, never on macOS. --local saves its public binding in deploy/stack.env so routine operations, source updates, and the existing image updater retain their workflows without adding Nginx. Press Ctrl+C to stop following logs.

Inspect status & logs
./deploy/stack.sh status
./deploy/stack.sh logs
Stop services (retain data volumes)
./deploy/stack.sh down
Start with existing images & apply configuration
./deploy/stack.sh start

After editing runtime settings in deploy/stack.env, use start to recreate containers. A restart alone does not load changed environment variables. Rebuild source deployments with up --source while retaining configuration. Existing image update methods remain unchanged.

Troubleshooting & retries

Reruns cannot change an existing installation’s ref, domain, port, or initial email. Inspect errors and logs first; retain the data volumes and original keys during recovery.

SymptomWhat to check
Installer download returns 404Confirm the script exists on the selected branch and is anonymously downloadable. A private repository or unpublished file cannot be installed with this public download command.
Missing Docker or required toolsThe entry installer does not install dependencies. Prepare Docker, Compose v2, Buildx, Bash, OpenSSL, curl, and tar first. Run the separate Ubuntu 26.04 Docker installer explicitly when needed.
Docker is unavailableCheck docker info, docker compose version, and docker buildx version. Ensure the local daemon is running and accessible; avoid remote Docker contexts.
Build is slow or downloads failCheck registry, npm/pnpm, and Go module connectivity, plus server memory and disk. Retry with the same directory after fixing the problem; retain configuration and data.
Public IP and port time outConfirm --public, BOSAPI_BIND_IP=0.0.0.0 in stack.env, and a 0.0.0.0:18080 container binding. Allow inbound TCP 18080 from the visitor’s IP in the attached security group, then check the host firewall. Default loopback deployments still need an SSH tunnel or --domain on first installation.
CLI works but the browser shows 502Compare server-local access, external curl --noproxy "*", and the browser. Healthy containers or one 200 response do not establish browser recovery. Check browser proxy extensions, PAC rules, and system proxy settings. Disabling the system proxy may leave extension proxying active, including in incognito windows.
Unknown --local or --public optionUse a complete source revision that supports both flags, including its matching install.sh and Compose manifest. Do not replace only the entry script.
Existing directory or old volumes detectedThe download workflow does not adopt unmanaged directories. Use --local for an existing complete application checkout and reuse its private configuration. If old data exists but stack.env is missing, restore the original configuration and encryption key.
Existing public source installation: retry in place
./install.sh --local --public --port 18080

Keep the original options and configuration. Rebuilds the current source without fetching Git updates or resetting passwords or data. Repeat the original flags for private or HTTPS installations.

Archive workflow: retry after source or configuration was saved
sudo sh /opt/bosapi/install.sh --dir /opt/bosapi

If failure preceded source-directory creation, repeat the original download command. Archive reruns do not upgrade source. Neither mode resets passwords or redisplays existing initial passwords.

Backups, upgrades & references

  • Back up the original deploy/stack.env, MySQL data and migration history, Redis, and gateway data. Include https.enabled and Caddy volumes for HTTPS. Keep an off-host copy and verify restoration.
  • For a consistent backup across components, pause writes or stop the stack in a maintenance window. Do not copy a live MySQL data directory. Existing encrypted data requires the original encryption key.
  • Downloaded archives have no .git metadata; neither git pull nor installer reruns upgrade them. --local does not fetch Git updates and builds only the source already in the directory. Verify backups, prepare the reviewed target source, preserve private configuration and markers, then use the existing upgrade and verification workflow.
  • Later stack.sh up --source, start, up --image, and the existing image updater reuse BOS_WEB_DELIVERY=go and BOSAPI_BIND_IP=0.0.0.0 saved by --local --public. Keep the original stack.env during code updates; no Nginx installation is needed.
  • Application rollback does not reverse database migrations. Confirm schema compatibility before using an older image, or restore a coordinated backup.

Match capabilities and procedures to your deployment version. Read the documentation scope

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free