Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview
On this page

Quickstart

Install the CLI, point it at your orchestrator, and bring up your first environment

This walks through the fastest path from a fresh machine to a running environment.

You need two things already up before you start:

The CLI does not run VMs itself. It is a client: it talks to the orchestrator, and the orchestrator talks to your hosts.

1. Install the CLI

brew install --cask folsomintel/fuse/fuse

Upgrade later with brew upgrade --cask folsomintel/fuse/fuse. Check what you have with fuse --version.

Without Homebrew

curl -fsSL https://raw.githubusercontent.com/folsomintel/fuse/main/ops/install-fuse.sh | bash

Works on macOS and Linux. The script resolves the latest release for your platform, verifies the archive against that release’s checksums.txt before extracting anything, and installs to /usr/local/bin (falling back to ~/.local/bin when that is not writable). VERSION=vX.Y.Z pins a release; FUSE_INSTALL_DIR=/path chooses the target.

On macOS this is also the path that avoids Gatekeeper entirely: curl does not set the com.apple.quarantine attribute that a browser download or a Homebrew cask does, so the first-launch check never runs. If you did download the archive through a browser and macOS refuses to open the binary, clear the attribute:

xattr -dr com.apple.quarantine ./fuse

Or grab the fuse-cli_* archive for your platform straight from the latest release.

2. Set up

fuse quickstart

One guided pass that does the whole first-time setup: it connects to your orchestrator, registers a compute host, and selects that host so later commands are scoped to it.

It prompts for the orchestrator URL and token, then the host’s ID, agent URL, and agent token, plus a region and a max VM count. CPU, RAM, and storage are not asked for, they are probed from the host agent. See fuse quickstart for every prompt and what it means.

quickstart is interactive. On a non-tty, run the two steps it wraps directly:

fuse connect https://orch.example.com --token "$ORCH_AUTH_TOKEN"
fuse host register prod-east-1 \
  --url http://10.0.0.5:8090 \
  --token "$FC_AGENT_TOKEN" \
  --max-vms 20

See CLI overview for global flags, contexts, and config file layout.

3. Scaffold a Fusefile

fuse init

This writes a fully commented example Fusefile to the current directory. Open it and adjust resources, run, and any services you need. See Fusefile for the full field reference.

Underneath the comments, the common case is small:

version: 1

resources:
  cpus: 2
  memory: 2GB

run: ./start.sh

That is the whole shape: how big the box is, and what to run on it. Nothing here names a vendor or a backend. GPU fields exist, and they are opt-in, see Advanced: GPU fields when you need one.

Line one of the scaffold is a yaml-language-server modeline pointing at Fuse’s published JSON Schema, so an editor with YAML support gives you completion and inline validation while you edit. It is a comment, and removing it changes nothing except that feedback. See Editor support.

The scaffold is deliberately maximal, it names every field. For the opposite end of the range, the fewest lines that actually boot, see Your first Fusefile. That version needs no --secret in step 4.

4. Bring it up

fuse up --secret pg_password=devpassword

up compiles the Fusefile and creates an environment from it, then streams provisioning events until the environment is up, exiting once it reaches running (or pass --no-wait to return immediately). If the environment ends up failed instead, up exits non-zero.

The scaffold from step 3 declares pg_password under secrets, so up refuses to create anything until you supply a value for it, either with --secret as above or with --secrets-file. Values live outside the Fusefile by design, the file names the secrets an environment requires rather than carrying them.

5. Check on it

fuse environment list
fuse environment get <id>
fuse environment exec <id> -- echo hello

Next steps

Was this page helpful?