Skip to main content

​
Install

Already followed Getting Started? You can usually continue there. This page is for install methods, platform notes, hosting profiles, and maintenance.

​
System requirements

On Windows, use WSL2 and run Fased inside Ubuntu.

​
Pick local or VPS hosting

These are different setup paths. Choose Local for a laptop, desktop, dev box, or WSL2. Choose VPS Hosting only on the server that will run Fased all the time.
Use this on your own machine:
git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh
Local setup keeps the Gateway on this machine and does not apply VPS SSH or firewall hardening. Tailscale is optional for Local.
The installer is repo-backed from fased-ai/fased.
Do not use normal local fased onboard on a laptop to configure a remote VPS. Run the hosted install on the VPS itself. If you choose Hosting from a session that cannot apply host security, onboarding stops with “Hosted setup unavailable” instead of creating an incomplete hosted setup.

​
Basic installer command

git clone https://github.com/fased-ai/fased.git fased
cd fased
./install.sh
The installer:
  • checks the host environment
  • checks Node and installs supported Linux dependencies when needed
  • installs the fased CLI
  • runs onboarding by default
  • opens the path to the browser Control UI
To install the CLI/runtime without onboarding: 
./install.sh --no-onboard
For flags and automation details, see Installer Reference.

​
Updating after install

Use fased update for normal updates. On a hosted VPS, log in as the app user through Tailscale first: 
tailscale ssh app@YOUR_VPS_TAILSCALE_NAME
fased update status
fased update
The browser Control UI can also run Update & Restart when the gateway is healthy. Rerun ./install.sh for repair/reinstall behavior; the current installer fast-forwards a clean Git checkout before building unless --no-git-update is set.

​
What onboarding does

Onboarding creates the baseline runtime: state directory, config, workspace, Gateway service, dashboard access, and selected hosting posture. It does not configure every Agent capability. After install, continue in the Control UI from the selected Agent:
  1. Models
  2. Chat
  3. Channels
  4. Services
  5. Skills / Tools
  6. Memory
  7. Tasks
  8. Wallets, Mining, and Fased Network only when you intentionally enable them
Pre-launch installs keep Satcoin runtime IDs empty. After official Satcoin mainnet proof is published, use Mining > Sync to verify the signed manifest and write config/sat-runtime.env.

​
VPS hosting posture

For a hosted or VPS runtime:
  1. start from a clean Linux VPS
  2. create/sign into Tailscale and join the VPS to your tailnet with sudo tailscale up --ssh
  3. run ./install.sh --hosting or choose Hosting during onboarding
  4. after onboarding, reconnect as app through Tailscale SSH
  5. avoid exposing the raw Gateway port publicly
Normal manual setup does not need a Tailscale API key. If the VPS is not logged in, Tailscale prints a login URL in the SSH terminal. Open that URL in your local computer’s browser, then return to the SSH session. Use --ts-authkey only for non-interactive provisioning. If Tailscale is missing or not logged in, Hosting onboarding tries to install or start it. If it cannot get a valid tailnet IP, it refuses to apply the SSH/UFW lockdown because you could lose remote access. Use VPS hosting, Hetzner, or GCP for provider-specific commands.

​
Install method map

MethodStatusUse when
Repo-backed install.shRecommended public pathmacOS, Linux, WSL2, local laptop, or VPS runtime
Source checkoutContributor pathYou want to build, test, or patch the repo directly
Hosted/VPS profileSupportedYou want an always-on Linux host with private access first
DockerSupported optional pathYou want a containerized Gateway or sandbox validation
PodmanSupported container pathYou want rootless containers on Linux
NixAdvanced/declarative pathYou already manage runtimes with Nix/Home Manager
BunExperimental dev pathYou want local TypeScript iteration; use Node for the Gateway runtime
Remote client modeSupported client modeThis machine should connect to an existing Gateway
Task worker installSupported after setupYou want separate task workers once a Gateway/runtime already exists

Docker

Containerized Gateway and sandbox reference.

Podman

Rootless container path for Linux.

Nix

Declarative install path for Nix users.

Node.js

Runtime version and PATH troubleshooting.
Public npm/pnpm global installation is not the normal public setup path yet. Use the repo-backed installer until a package release is published and documented.

​
Validate install

fased doctor
fased status
fased dashboard
Good result:
  • fased doctor reports no blocking setup errors
  • fased status shows the Gateway target you expect
  • fased dashboard opens an auth-ready Control UI link

​
After install

Use this order for a new runtime:
  1. verify runtime health
  2. confirm private operator access
  3. configure model access
  4. send a first chat message
  5. add channels and services as needed
  6. define wallet and signer posture before using wallet-related features
  7. enable Mining or Fased Network only after the base runtime is stable
Successful installation means the runtime exists. It does not replace the setup checks for channels, services, wallets, mining, or network roles.

​
Troubleshooting: fased not found

Quick diagnosis:
node -v
ls -l "$HOME/.local/bin/fased"
echo "$PATH"
The repo-backed installer writes the launcher to ${FASED_CLI_BIN_DIR:-$HOME/.local/bin}/fased. If $HOME/.local/bin is not on your PATH, your shell cannot find fased.Fix by adding it to ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.local/bin:$PATH"
Then open a new terminal, or run rehash in zsh / hash -r in bash.

​
Update, migrate, uninstall

Updating

Refresh the repo-backed runtime.

Migrating

Move state and workspace to a new machine.

Uninstall

Remove services, CLI, and state.