Skip to main content

​
Installer Reference

This docs set only documents the installer that exists in this repo: If you are starting from zero, the normal path is: 
git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh
On Windows, use WSL2, then run the same repo-backed commands inside Ubuntu.

​
What install.sh does

1

Detect the host environment

Supports macOS, Linux, and WSL2.
2

Ensure a compatible Node.js runtime

Fased recommends Node 24 and requires Node 22.14 or newer with the built-in node:sqlite module. On supported Linux hosts, the installer can install missing dependencies when auto-install is enabled.
3

Ensure Git

Installs Git if it is missing.
4

Prepare the repo-backed runtime

Uses the checkout and install flow this repository actually supports for public use. Current installers attempt a fast-forward-only update from origin before dependency install and build. If source changes during that update, the installer restarts once so the new installer code runs.Local installs check for existing ~/.fased data before onboarding. If state already exists, the installer asks whether to keep it, reset local config metadata, or use a separate state directory for this checkout.If the install starts as root on a hosted server, the installer creates a non-root app user, prepares /home/app/fased, and re-runs itself there. The runtime and CLI are then owned by app.
5

Install the CLI launcher

Installs the repo-backed fased command into the user command path and verifies it before onboarding.By default this is ${FASED_CLI_BIN_DIR:-$HOME/.local/bin}/fased; the installer also tries to add that directory to common shell startup files.
6

Run onboarding when appropriate

If onboarding is enabled, the installer hands off to fased onboard --install-daemon. On low-memory Linux hosts, the installer creates swap automatically when possible and onboarding runs with a larger V8 heap limit. Override with FASED_ONBOARD_MAX_OLD_SPACE_MB only for troubleshooting.For a hosted or VPS runtime, the intended sequence is:
  1. create or sign into your Tailscale account
  2. join the host to your tailnet
  3. run onboarding with the hosting profile
  4. when prompted, test ssh app@YOUR_VPS_TAILSCALE_NAME from your own computer
  5. confirm only after SSH reaches /home/app/fased
  6. open the printed Tailscale dashboard URL in your local browser
  7. save the gateway token in case the browser asks for it
  8. reconnect as the non-root app user over the Tailscale network for CLI work
  9. keep admin access private through Tailscale instead of opening the gateway directly
Root is the bootstrap/emergency shell. After hosted onboarding completes, normal commands run as app; the shell starts in /home/app/fased:
ssh app@YOUR_VPS_TAILSCALE_NAME
fased status
fased dashboard
Non-interactive automation must only set FASED_HOSTING_TAILNET_SSH_CONFIRMED=1 after an out-of-band check proves the app SSH path over Tailscale works. Without that explicit confirmation, hosting setup stops before SSH/firewall lock-down.
7

Leave SAT IDs for Sync

Pre-launch installs keep config/sat-runtime.env empty. After Satcoin mainnet launch proof is published, use Mining Sync to verify the signed manifest and write the official SAT runtime IDs.

​
Quick commands

From the repo root: 
./install.sh

./install.sh --help

./install.sh --no-onboard

./install.sh --verbose
Fresh machine, one copy-paste block: 
git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh
Hosting note:
  • do Tailscale setup before onboarding
  • when Tailscale prints a login URL in SSH, open it in your local browser
  • use an auth key only for unattended automation
  • use the hosting profile in the wizard
  • keep access tailnet-only unless you later make a deliberate, separately-audited exposure choice

​
Common modes

./install.sh
Runs onboarding by default.

​
Common public flags

These are the flags that matter for the current public repo-backed flow.
FlagDescription
--auto-installInstall missing Linux dependencies with apt where supported.
--no-auto-installDo not install missing dependencies automatically.
--install-dir <path>Bootstrap or resolve the checkout under a specific directory.
--hostingUse hosted/VPS onboarding defaults.
--localUse local-machine onboarding defaults.
--swap-gb <n>Override automatic install-time swap sizing on small Linux hosts.
--no-onboardBuild/install and skip onboarding.
--verboseShow install command output instead of only log paths.
--helpShow usage (-h).
Extra arguments after -- are forwarded to fased onboard --install-daemon.
The script may still contain additional internal or legacy flags. For the exact current surface, run ./install.sh --help from the repo root.

​
Environment variables

VariableDescription
FASED_INSTALL_REPO=<url>Repo URL used by bootstrap installs.
FASED_INSTALL_DIR=<path>Checkout/install directory.
FASED_STATE_DIR=<path>Runtime state directory for config, sessions, credentials, logs, wallets, and caches.
FASED_CONFIG_PATH=<path>Explicit config file path. Defaults to $FASED_STATE_DIR/fased.json.
FASED_CONFIG_DIR=<path>Installer compatibility alias for state, install marker, cache, and logs directory. Prefer FASED_STATE_DIR for new installs.
FASED_CLI_BIN_DIR=<path>Directory where install.sh writes the fased command.
FASED_INSTALL_VERBOSE=1Show install command output instead of only log paths.
FASED_INSTALL_USER=<name>Non-root app user used by root bootstrap installs.
FASED_EXISTING_DATA_ACTION=<mode>Advanced local state override: keep, reset-config, or separate-state. Normal installs keep existing state automatically.
FASED_EXISTING_DATA_DIR=<path>State directory used with FASED_EXISTING_DATA_ACTION=separate-state.
FASED_SAT_RUNTIME_ENV_FILE=<path>Optional SAT runtime ID env file for explicit test networks or verified manual recovery. Normal mainnet setup uses Mining Sync.

​
Automation

Headless repo-backed install: 
git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh --no-onboard
If you automate a hosted install, keep the same security order:
  1. provision the host
  2. join it to Tailscale; use an auth key only for non-interactive provisioning
  3. run onboarding
  4. access Control UI / gateway only through Tailscale or a deliberate private tunnel
Use a controlled install directory in CI or on a managed host: 
git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh --install-dir "$HOME/agent" --no-onboard

​
Not public install paths yet

Direct npm install -g, pnpm add -g, or Bun global package installs are not the current public setup path. They can come back after package publication and release automation are ready. Until then, the supported public path is the repo-backed installer.