# Scion

Run multiple agents in parallel — each in its own container, with its own workspace, collaborating on your code or project files simultaneously.

_sci·on /ˈsīən/ — a young shoot or twig, cut for grafting or rooting._

Scion is an experimental multi-agent orchestration testbed designed to manage "deep agents" running in containers.


Scion orchestrates "deep agents" (Claude Code, Gemini CLI, and others) as isolated, concurrent processes. Each agent gets its own container, (optional) git worktree, and credentials — so they can work on different parts of your project without stepping on each other. Agents run locally, on remote VMs, or across Kubernetes clusters.

Rather than prescribing rigid orchestration patterns, Scion takes a "less is more" approach: agents dynamically learn a CLI tool, letting the models themselves decide how to coordinate among agents. This makes it a rapid prototype testbed for experimenting with multi-agent patterns through natural language prompting. Read more in [Philosophy](https://googlecloudplatform.github.io/scion/philosophy/).


## In Action

While Scion is powered by coding agents, and can absolutely be used for multi-agent software development, it isn't exclusive to software development, but is a orchestration tool and layer, which can be combined with other agent augmenting system (task tracking, memory, etc - see below on compliments to Scion). We have used it internally at Google for exploring software porting, used for market research, product testing, and more. We are exploring it for use in Cloud operations, and scientific research.  Below are a couple other demonstrations of how agents can collaborate in interesting scenarios.

### Scion Films

<img height="200" alt="scion-films-poster" src="https://github.com/user-attachments/assets/51be1c80-4bb3-48ad-90e9-356aeffcb678" />


The [Scion Films](https://films.scion-ai.dev/) project was an exploration in how to iterate and improve multi-agent orchestration, skills, and tools in a domain that is not as innate or "verifiable" as classic auto-research problems where a simple computable scoring metric was used. Instead, human viewer feedback and agent retrospectives were used to iterate across a series of "pilots" - for fun, we use agents to document the entire proces, and in the end, they used the same refined tools and process to make a documentary film.

### Relics of Athenaeum

[Relics of Athenaeum](https://github.com/ptone/scion-athenaeum) is an "agent game" that demonstrates multi-agent orchestration defined entirely in markdown. A group of agents collaborate to solve computational puzzles, coordinating through group and direct messaging — all running in containers on off-the-shelf harnesses.

<a href="https://github.com/ptone/scion-athenaeum"><img height="200" alt="Relics of Athenaeum" src="https://github.com/user-attachments/assets/cbee74a3-f3aa-4739-b423-0a83d5dd4c13" /></a>&nbsp;<a href="https://www.youtube.com/watch?v=w16bsh6lFL8"><img height="200" alt="Visualization of agent coordination" src="https://github.com/user-attachments/assets/a615da24-33d8-4882-abe1-95adea4ed79a" /></a>

The visualization above replays the actual telemetry collected from messages and file access in the shared workspace while the agents solved the challenges of the game. While this is a "game", the same process of team definition works for software engineering, data research, and platform engineering workflows.

## Scion architecture companions

Scion acts as a core component in a multi-agent solution, but does not try to package all capabilities into a monolithic and over-opinionated solution, instead trying to offer value in durable and well structure abstractions and primitives.  In that sense it is like a game engine upon which you build your game title. First and foremost this comes down to defining your own agent templates, which increasingly are based on skills. If you are doing software factory work, you will want some task management system which could be Github issues, Linear, or something more agent-centric like [Farmtable](https://github.com/scion-frontiers/farmtable), or [Beads](https://github.com/gastownhall/beads). You also might want to introduce a component that manages agent memory (although Scion's use of shared filesystem may get you a long way), network proxy access, etc.

## Quick Start

### Install with Homebrew (recommended)

The easiest way to get Scion is the community [homebrew-scion](https://github.com/homebrew-scion/homebrew-scion) tap:

```bash
brew tap homebrew-scion/scion
brew install homebrew-scion/scion/scion
```

This installs the `scion` CLI — pre-configured to use `ghcr.io/homebrew-scion` as the default image registry — along with the `scion-plugin-telegram` broker plugin. To upgrade later:

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

Then start the Workstation server:

```bash
scion server start
```

Your browser opens to the onboarding wizard at `http://127.0.0.1:8080/onboarding`, which walks you through runtime detection (Docker, Podman, or Apple Container), identity configuration, container image setup, and creating your first workspace.

After onboarding, start your first agent:

```bash
scion start my-agent "Your task here"
```

See the [homebrew-scion tap](https://github.com/homebrew-scion/homebrew-scion) for the full list of pre-built multi-arch container images and distribution details.

### Install from Source

See the full [Installation Guide](https://googlecloudplatform.github.io/scion/getting-started/install/), or install from source (requires Go 1.22+):

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

> **Warning:** `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` before installing the binary.

### Initialize your machine and a Project (project)

> **Tip:** If you used `scion server start` above, the onboarding wizard handles machine initialization automatically — you can skip this section.

Navigate to your project and create a Scion project (the `.scion` directory that holds agent config):

```bash
scion init --machine
cd my-project
scion init
```

> **Tip:** Add `.scion/agents` to your `.gitignore` to avoid issues with nested git worktrees.

Scion auto-detects your OS and configures the default runtime (Docker on Linux/Windows, Container on macOS). Override this in `.scion/settings.yaml`.

**NOTE** Currently this project is early and experimental. Most of the concepts are settled in, but many features may not be fully implemented, anything might break or change and the future is not set. Local use is relatively stable, Hub based workflows now highly usable, Kubernetes runtime support still has rough edges.

### Start Agents

```bash
# Start and immediately attach to the session
scion start debug "Help me debug this error" --attach
```

### Manage Agents

| Command | Description |
|---------|-------------|
| `scion list` (`ps`) | List active agents |
| `scion attach <name>` | Attach to a running agent's tmux session |
| `scion message <name> "..."` (`msg`) | Send a message to a running agent |
| `scion logs <name>` | View agent logs |
| `scion stop <name>` | Stop an agent |
| `scion resume <name>` | Resume a stopped agent |
| `scion delete <name>` | Remove agent, container, and worktree |

## Key Features

- **Harness Agnostic** — Ships with Gemini CLI and Claude Code by default. Additional harnesses (OpenCode, Codex, Antigravity) are available as [opt-in bundles](harnesses/README.md). Adaptable to anything that runs in a container.
- **True Isolation** — Each agent runs in its own container with separated credentials, config, and a dedicated `git worktree`, preventing merge conflicts.
- **Parallel Execution** — Run multiple agents concurrently as fully independent processes, locally or remotely.
- **Attach / Detach** — Agents run in `tmux` sessions for background operation. Attach for human-in-the-loop interaction, enqueue messages while detached, and tunnel into remote agents securely.
- **Specialization via Templates** — Define agent roles ("Security Auditor", "QA Tester") with custom system prompts and skill sets. See [Templates](https://googlecloudplatform.github.io/scion/local/templates/).
- **Multi-Runtime** — Manage execution across Docker, Podman, Apple containers, and Kubernetes via named profiles.
- **Observability** — Normalized OTEL telemetry across harnesses for logging and metrics across agent swarms.

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Agent** | A containerized process running a deep agent harness (Claude Code, Gemini CLI, etc.) |
| **Project** | A project namespace and collection of agents, commonly 1:1 with a git repo |
| **Template** | An agent blueprint — system prompt plus a collection of skills |
| **Runtime** | A container runtime: Docker, Podman, Apple Container, or Kubernetes |
| **Hub** | Optional central control plane for multi-machine orchestration |
| **Runtime Broker** | A machine (laptop or VM) offering its runtimes to a Hub |

Not all concepts apply in every scenario — local mode is simpler. See [Concepts](https://googlecloudplatform.github.io/scion/concepts/) for the full picture.

## Documentation

Visit our **[Documentation Site](https://googlecloudplatform.github.io/scion/)** for comprehensive guides and reference.

- **[Overview](https://googlecloudplatform.github.io/scion/overview/)**: Introduction to Scion.
- **[Installation](https://googlecloudplatform.github.io/scion/getting-started/install/)**: How to get Scion up and running.
- **[Concepts](https://googlecloudplatform.github.io/scion/concepts/)**: Understanding Agents, Projects, Harnesses, and Runtimes.
- **[CLI Reference](https://googlecloudplatform.github.io/scion/reference/cli/)**: Comprehensive guide to all Scion commands.
- **Guides**:
    - [Using Templates](https://googlecloudplatform.github.io/scion/local/templates/)
    - [Using Tmux](https://googlecloudplatform.github.io/scion/local/tmux/)
    - [Kubernetes Runtime](https://googlecloudplatform.github.io/scion/hosted/ha/kubernetes/)

## Project Status

This project is evolving and experimental. Core concepts are settled, but expect rough edges:

- **Local mode** — relatively stable. Increasingly focused on local "workstation" mode where a full local server runs.
- **Single-node Hub** — Mature and is in use for many projects inside google
- **Distributed HA** — early, with known rough edges

See the [public roadmap](https://github.com/orgs/scion-frontiers/projects/5/views/2) for details.

## Disclaimers

This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).

## License

Apache License, Version 2.0. See [LICENSE](LICENSE).