Skip to content

SETUP.md

Latest commit

 

History

History
125 lines (87 loc) · 7.47 KB

SETUP.md

File metadata and controls

125 lines (87 loc) · 7.47 KB
Raw

PortOS Setup Guide

PortOS can automate local installation, certificate provisioning, and launch URLs, but two account-level decisions stay with you: joining a Tailscale tailnet and choosing which AI provider may run work. The CLI and Settings → Setup show the same ordered readiness checks so a missing prerequisite is visible instead of becoming a broken URL later.

First install

git clone --recurse-submodules https://github.com/atomantic/PortOS.git
cd PortOS

Choose the database before setup

Setup provisions only the selected backend; it does not detect and choose between Docker and native PostgreSQL.

  • Docker (default): install and start Docker with Compose available before running setup. With no PGMODE configured, PortOS uses Docker on port 5561.
  • Fresh native install: create or edit .env in the repository root and set PGMODE=native, preserving other settings. The default endpoint is localhost:5432; set PGHOST and PGPORT there if needed. Setup checks that endpoint and, if it is not ready, invokes the native bootstrap in scripts/db.sh setup-native (Homebrew provisioning).

A nonempty exported PGMODE overrides .env; an empty one counts as unset. Setup and PM2 (ecosystem.config.cjs) share this precedence; unset a conflicting shell value before setup. If Docker is selected but unavailable, setup fails even if native PostgreSQL is healthy. It leaves the selection unchanged so a missing Docker daemon cannot silently redirect an existing install to another database.

Existing installs: retain the backend holding your records. Editing PGMODE or rerunning setup does not migrate them. Use the coordinated cutover in Settings → Database to move between backends; see Database backend migration. For endpoint overrides and readiness checks, see Storage setup.

Run the installer

./setup.sh                 # macOS / Linux guided installer
# or: .\setup.ps1         # Windows PowerShell

npm run setup is the non-wrapper equivalent. All three paths install dependencies, provision PostgreSQL, prepare runtime data and the managed browser, ask about a local LLM when an interactive terminal is available, safely attempt Tailscale certificate provisioning, and print the remaining setup walkthrough.

Network setup

The network sequence is:

  1. Install Tailscale on the PortOS host.
  2. Open Tailscale and sign the host into your tailnet.
  3. Enable MagicDNS and HTTPS Certificates in the Tailscale DNS admin.
  4. Let PortOS run tailscale cert with npm run setup:cert.
  5. Restart PortOS and open the exact URL printed by setup: https://<machine>.<tailnet>.ts.net:5555.

The installer performs step 4 automatically whenever the preceding account settings are ready. If an account setting is missing, it exits successfully with the exact next action; it never waits for a hidden prompt and never substitutes an untrusted self-signed certificate unless you explicitly pass --self-signed.

URLs and ports

  • :5555 is always the user-facing PortOS port. It serves HTTP before a certificate exists and HTTPS after the trusted certificate is active.
  • http://localhost:5553 is a host-only HTTP mirror when HTTPS is active. It exists for local scripts and does not work from another device.
  • :5554 is only the Vite development UI.

Run npm run setup:guide at any time to print the current walkthrough and correct URL. Add -- --summary for one line or -- --json for automation. PortOS's managed browser also opens the trusted MagicDNS URL when one is provisioned rather than defaulting to localhost.

Instance password

Authentication is optional and off by default. Set a strong, unique password in Settings → Security to protect the instance API and data. First-time setup requires a browser on the PortOS host using a loopback URL: use http://localhost:5555 without HTTPS, the local mirror http://localhost:5553 with HTTPS, or http://localhost:5554 for the local Vite UI. A LAN/tailnet URL or a remote browser relayed through Vite cannot set the first password; the Security page displays the host-control refusal.

Once configured, sign in from your other devices over the private network. Changing the password requires both an operator session and the current password, and signs out existing sessions. Peer credentials cannot change it.

Choose an AI provider

Initial setup is complete once at least one enabled provider is actually runnable. Choose one path under AI → Providers:

  • Subscription CLI: install and authenticate a supported CLI such as Claude Code, Codex, or Antigravity. This is the recommended cost model for sustained autonomous work.
  • API provider: add a key for the paid provider you intend to use. PortOS never enables a paid provider automatically.
  • Local/private: install Ollama or LM Studio and download a compatible model under Models → LLMs.

The Setup page checks binaries, credentials, local runtimes, and models without making an LLM request. PortOS never performs cold-bootstrap model calls.

Setup guidance in the app

After PortOS starts:

  • The global setup banner names the next missing essential and links to Settings → Setup. “Later” hides only the current state for the browser session.
  • Settings → Setup keeps the complete network walkthrough and AI-provider choice above optional capability health.
  • The Dashboard's Network Exposure widget shows the next network action.
  • Dev Tools → Instances exposes the same full network guide alongside peer MagicDNS suggestions.

Certificate provisioning and the PortOS restart are one-click actions in the UI once MagicDNS and the Tailscale admin certificate toggle are ready.

Updates and recovery

update.sh, update.ps1, and the in-app updater retry the safe certificate provisioning step on every update, report the current network prerequisite in update progress, and print the full walkthrough afterward. An update does not fail merely because Tailscale is absent or an account toggle still needs you.

Updates check the pulled version's Node.js requirement (the same scripts/checkNodeVersion.js gate that npm start uses) before stopping any app or installing dependencies. If your Node.js is too old, the update stops with the required range and leaves PortOS running; the checkout is already on the new revision, so upgrade Node.js (for example nvm install using .nvmrc) and re-run the update.

Useful checks:

npm run setup:guide       # ordered network + provider walkthrough
npm run setup:cert        # retry trusted Tailscale certificate provisioning
npm run doctor            # read-only report of all install prerequisites
npm run pm2:restart       # activate a newly provisioned certificate

For HTTPS without Tailscale, npm run setup:cert -- --self-signed remains an explicit fallback. Browsers will warn because that certificate is not publicly trusted, and a stable MagicDNS URL is still preferable for remote use.

Grok Bot box / CPU-only Persistent Mind

On a CPU-only ~16 GB host (for example a Grok Bot box with no GPU), prefer a free local Persistent Mind on Ollama + qwen2.5:7b-instruct, and keep Cursor Agent / OpenCode Zen for coding. PortOS offers that setup on AI Providers, Models → LLMs, and Persistent Mind → Settings. See features/grok-box-local-mind.md.