Installation

What you will learn: How to get Scion running on your machine from scratch, up to the point where you can start your first agent.

This guide covers the steps to install and configure Scion on your local machine. Scion runs agents through a hub. On your own machine that is Workstation mode: the combo server (Hub, Runtime Broker and web dashboard) on loopback, started with scion server start. To use a shared hub instead, install the CLI here and then follow Connecting to a Hub. If you are not sure which you want, read Choosing a Mode first.

Prefer a guided setup?

For Workstation mode, the Onboarding Wizard walks you through the whole setup in your browser — no config files to edit. Install Scion with Homebrew (below), then run scion server start.

Install with Homebrew (recommended)

The easiest way to get a ready-to-run Scion — CLI plus embedded web UI — is the community homebrew-scion tap:

brew tap homebrew-scion/scion
brew install homebrew-scion/scion/scion

This installs:

• scion — the main CLI, pre-configured to use ghcr.io/homebrew-scion as the default image registry, so the harness images are pulled for you.
• scion-plugin-telegram — the Telegram broker plugin, installed automatically alongside the CLI. To connect it, follow Setting Up Telegram.

To upgrade later:

brew update && brew upgrade homebrew-scion/scion/scion

Quick start

Start the Workstation combo server:

scion server start

Your browser opens to the Onboarding Wizard at http://127.0.0.1:8080/onboarding, which handles the rest of setup for you — runtime detection (Docker, Podman, or Apple Container), identity configuration, container image setup (pulling from ghcr.io/homebrew-scion), and creating your first workspace.

After onboarding, start your first agent from the web UI, or from the CLI in a repository with scion init and scion start (see the Tutorial).

Using Homebrew?

The onboarding wizard performs machine initialization and image setup for you, so you can skip many of the Prerequisites and Configuration sections below — they apply to a from-source install or a manual setup without the wizard. You will still need a container runtime - podman is recommended.

---

Prerequisites

These apply when you build from source or configure Scion manually. The onboarding wizard checks the runtime and Git requirements for you.

1. Go

Go is required only to build Scion from source. You need Go 1.26 or later installed (see the go directive in the repository’s go.mod). Homebrew installs a prebuilt binary, so you can skip this if you installed with brew.

• Download and install Go

2. Container Runtime

Scion requires a container runtime to manage agents. You can use Docker, Podman, or the Apple Virtualization Framework (experimental).

When no runtime is configured, Scion picks one automatically. On macOS it prefers Podman, then Docker, then Apple container. On macOS, when Podman is selected or auto-detected but not on your PATH, Scion also looks for it in /opt/podman/bin, /usr/local/bin and /usr/bin when it uses the runtime. Detection during setup, including the onboarding wizard’s, looks only on your PATH and checks that each runtime runs; on Linux it prefers Podman, then Docker. To use another installed runtime, select it in the onboarding wizard or in your profile’s runtime setting.

Docker (Linux/Windows)

• Install Docker Desktop or Docker Engine.
• Ensure the docker command is available in your PATH.

Podman (Linux/macOS)

• Install Podman.
• Ensure the podman command is available in your PATH.
• On Linux, Scion supports rootless Podman out of the box.
• On macOS, ensure podman machine is initialized and running.

Apple Virtualization (macOS only)

• Requires the container tool (an Apple tool for running OCI images in micro VMs).
• Ensure the container command executes.
• Start the system services container system start.
• Agents reach the hub from inside their containers. With Docker and Podman this works automatically. With Apple container it needs a sudo DNS rule that must be re-created after each reboot (or installed as a LaunchDaemon); the onboarding wizard’s runtime step shows the command. See Apple Container DNS. On macOS, auto-detection prefers Podman, then Docker, and picks Apple container only when neither is installed, so the DNS step applies when Apple container is the only runtime or you select it (see Select Runtime).

3. Git

Scion uses git worktree to manage agent workspaces.

• Ensure git is installed and available in your PATH.
• Because Scion uses a new feature for relative path worktrees, ensure that git --version >= 2.48.0.

For Ubuntu you can install the latest version with

add-apt-repository ppa:git-core/ppa

apt update; apt install git

On Debian, note that Debian 13 (trixie)’s own apt git is 2.47.3 — below the 2.48 floor. Check git --version; if it’s too old, build from source (see the git site) or install a newer package from a source like git-scm.com’s Linux downloads.

---

Install from Source

Building from source is the alternative to Homebrew — use it if you are contributing to Scion or prefer to build the binary yourself.

From Source (go install)

You can install Scion directly using go install:

go install github.com/GoogleCloudPlatform/scion/cmd/scion@latest

Web UI assets are not included

go install builds only the Go binary. It does not build or embed the web frontend, so scion server start will serve a blank web UI with missing frontend assets. Use Homebrew for a ready-to-run install, or build from a clone with make all.

Ensure your $GOPATH/bin (typically ~/go/bin) is in your system $PATH.

From Clone

If you have the repository cloned, you can use the provided Makefile:

make all
# This creates a 'scion' binary in the build directory.
# You can move it to a directory in your PATH:
sudo mv ./build/scion /usr/local/bin/

The all target builds the web frontend before compiling the Go binary, so the embedded web UI assets are present. If you prefer separate steps, run make web before make build.

To verify your installation, run:

scion version

---

Build container images

No publicly hosted images are currently available for Scion, but quick and easy build scripts are included.

The easiest way to get these images is to fork this repo, and then go to the “Actions” tab and select the “Build Scion Images” workflow.

You will then use your ghcr.io/myorg registry for the image_registry setting. These images must be available in the registry before running the initialization command.

See Building Containers for more details

Configuration

1. Initialize your machine

You must first establish global settings, templates and configs for your machine

scion init --machine

This creates a directory at ~/.scion

You will be prompted for the image registry where you have built and deployed the images in the previous step.

2. Initialize a Project

Navigate to the root of a project where you want to use Scion and run:

scion init

This creates a .scion marker file in the directory, linking it to structures inside the global folder created on the machine initialization. When a hub is running (next step), init also links the project to it; otherwise it prints a note and the project links on its first scion command.

3. Start the local hub

Agents run through a hub. Start the workstation server once:

scion server start

It runs in the background, adds itself to your list of hubs as local (http://127.0.0.1:8080), and on the first run opens the Onboarding Wizard. Before any hub is set up, agent commands fail with:

No hub selected. Add one with 'scion hub add <name> <url>', start a local hub with 'scion server start', or pick one with 'scion use --hub <name>'.

Once the local hub is set up, commands run while it is stopped (for example after scion server stop) fail with:

Local scion server is not running. Start it with 'scion server start'.

To use a shared hub instead, see Connecting to a Hub.

4. Agent Authentication (LLM Access)

Before starting an agent, you must provide credentials so the underlying LLM harness (Claude, Gemini, etc.) can authenticate with its model provider.

Scion uses a unified authentication pipeline that automatically discovers credentials from your environment. For a quick start, export your provider’s API key:

# For Claude
export ANTHROPIC_API_KEY="your-api-key"

# For Gemini
export GEMINI_API_KEY="your-api-key"

On the workstation server, harness login files in your home directory (for example after you sign in to a harness on this machine) are given to agents automatically. Scion also supports Vertex AI (via Application Default Credentials). For advanced credential configurations, including Hub-based secret injection, see Agent Credentials.

5. Select Runtime

Scion automatically selects the first runtime it finds working, in this order:

• macOS: podman, then docker, then container (Apple Virtualization Framework).
• Linux/Windows: podman, then docker.

If you wish to change this (e.g., to use Apple container on macOS when Podman or Docker is also installed), you can manually edit .scion/settings.yaml:

profiles:
  local:
    runtime: container

Scion accepts settings in either YAML or JSON. scion init writes settings.yaml, and YAML is preferred when multiple files are present (the loader looks for settings.yaml, then settings.yml, then settings.json). If you prefer JSON, name the file .scion/settings.json and use valid JSON syntax:

{
  "profiles": {
    "local": {
      "runtime": "podman"
    }
  }
}

Both files validate against the settings JSON schema. See the Configuration Overview for the full settings ecosystem.

---

Next steps

• Run your first agent — follow the Tutorial.
• Set up Workstation mode — use the Onboarding Wizard (scion server start).
• Upgrading from a release that ran agents without a hub? See the migration page.
• Understand the pieces — read Core Concepts.

---

Shell Completions

Scion provides shell completions. These are highly recommended as they are very useful when providing proper descriptive agent names.

For setup instructions, see Shell Completions.

---

Troubleshooting

git worktree errors

Ensure your project is a git repository. scion init and scion start require being inside a git repository to manage workspaces.

Permission Denied (Docker)

Ensure your user has permissions to run Docker commands without sudo. On Linux, add your user to the docker group.

Path Issues

If scion command is not found after go install, add the following to your shell profile (.zshrc or .bashrc):

export PATH=$PATH:$(go env GOPATH)/bin