Fractal

Getting started

Install Fractal

Install the CLI, configure your identity, and start the daemon.

View raw Markdown ↗

Install Fractal

Requirements

  • Linux x86_64 with glibc 2.35 or later, or Apple Silicon macOS 15 or later.
  • curl, tar, and sha256sum or shasum; macOS also needs Python 3.
  • A supported coding harness installed and signed in as the same user who will run the daemon.

Neither Rust nor Nix is required for binary installation. Agents consume your provider's usage and quota and run commands with your user's access. Choose workspaces and tasks accordingly.

Download

Review the installer before running it if you prefer to inspect downloaded scripts.

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/compoundingtech/fractal/main/install.sh | sh -s -- --no-run
export PATH="$HOME/.local/bin:$PATH"
fractal --version

The installer downloads the latest release and checks its SHA256 sidecar. The archive and checksum come from the same release endpoint; this is an integrity check, not an independent signature. --no-run installs the commands without launching a client.

Set up your machine

Run fractal setup in your terminal. Choose your person name, a persistent machine name, which installed harnesses to integrate, and whether to keep the daemon running as a user service. The machine name local is reserved. Native harness login and workspace trust may need your interaction.

Setup describes each integration before changing it. A new installation uses the auto access mode: provider-managed permission checks reduce accidents but are not a security boundary. bypass removes those prompts. Do not change that setting without the user's authorization.

Use the CLI to inspect agents and missions. For graphical access, connect to an already configured web app: fractal web opens its URL but does not start a web server.

Check success

fractal --version
fractal doctor
fractal service status

Doctor should report a reachable daemon and available pty. A machine without a fleet is healthy. An installed harness is not necessarily authenticated: check the agent's readiness and finish its native first-run screens before continuing.

Next: declare your first agent. For declarative installation, see Home Manager. If a check fails, use troubleshooting.