Tutorial

This tutorial takes you from a fresh install to your first running agent. Scion runs agents through a hub. On your own machine that hub is the workstation server: one process with the Hub, a Runtime Broker and the web dashboard, listening on 127.0.0.1. You start it once, and every scion command in any repository uses it.

Before you start, install Scion and a container runtime (Docker, Podman, or Apple Container).

1. Start the local hub

scion server start

The server starts in the background and prints its URL. On the first start it also adds itself to your list of hubs as local, so later commands find it:

Registered hub 'local' (http://127.0.0.1:8080); rename with 'scion hub rename'.

On the first run your browser opens the Onboarding Wizard at http://127.0.0.1:8080/onboarding. It sets up your machine: runtime, image registry and harness images. Its last step, First workspace, is optional. You can skip it, because the next step links your repository from the command line.

Scion opens it through a single-use sign-in link (printed on a terminal as Sign in: http://127.0.0.1:8080/auth/dev-signin?code=...), which signs your browser in. If the browser does not open (over SSH, or with SCION_NO_BROWSER set), open that link yourself within two minutes, or run scion server open --print for a new one.

macOS with Apple container

On macOS, Scion prefers Podman, then Docker, and uses the Apple container runtime only when neither is installed or when you select it. With Apple container, agents can reach the hub only through a sudo DNS rule that must be re-created after each reboot (or installed as a LaunchDaemon). The wizard’s runtime step shows the command; run it yourself. See Apple Container DNS, including how to automate it after reboots.

No image registry yet?

Without an image_registry, the server starts the hub and the web UI but not the Runtime Broker, and prints how to set the registry. Set it in the wizard (or with scion config set --global image_registry <your-registry>), then run scion server restart; the restart picks up a registry saved in the wizard.

2. Initialize your repository

Go to a git repository you want agents to work on and initialize it:

cd ~/src/my-repo
scion init

scion init creates the project’s .scion directory and links the project to the local hub, without a prompt:

Linking project 'my-repo' to the local hub at http://127.0.0.1:8080

If the hub is not running, init still succeeds and prints a note; the project then links on its first scion command. init adds an untracked .scion/ and, unless it is already ignored, appends .scion/agents/ to your .gitignore.

Agents in this repository get a git worktree of your checkout, so git 2.48 or newer is required here; after the first agent, older git can no longer read this checkout.

3. Give agents model access

Agents need credentials for their model provider. On the workstation server, the harness login files in your home directory (for example after you sign in to Claude Code or Gemini CLI on this machine) are given to agents automatically; see Agent Credentials. Alternatively, export an API key in the shell you run scion from:

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

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

4. Start an agent

In the repository, give the agent a name and a task:

scion start my-first-agent "Write a python script that prints Hello World"

The agent runs in the background in its own container. It works in a git worktree of your checkout at .scion/agents/my-first-agent/workspace, on its own branch my-first-agent, so your working directory stays clean. It starts from your current commit: commits you have not pushed are there, uncommitted changes are not. See Linked git projects for how agents get their workspace and what is checked first.

Do not name an agent after the branch you have checked out: that agent would work directly in your own checkout.

5. List agents

scion list

The table shows each agent in the project with its template, harness config, Runtime Broker, phase and last activity. The same agents appear in the Web Dashboard at http://127.0.0.1:8080.

6. Check on an agent

See the agent’s recent terminal output, or its logs:

scion look my-first-agent
scion logs my-first-agent

If the agent needs your input, attach to its terminal session:

scion attach my-first-agent

To detach and leave the agent running, press Ctrl-b, then d (see Interactive Sessions with Tmux).

You can also start an agent and attach to it in one go:

scion start --attach my-other-agent

7. Clean up

When the agent has finished, review its changes: its branch my-first-agent is in your repository, so you can inspect and merge it as usual (for example git merge my-first-agent). When you no longer need the agent, delete it:

scion delete my-first-agent

This stops the agent’s container and removes its worktree. It also deletes the branch, including commits you have not merged, so merge what you want to keep first, or pass --preserve-branch.

Working from outside the repository

Inside a project directory, commands target that project. To work with the project from anywhere else, select it once as your current project:

scion use my-repo
scion list

Commands run outside a project directory now target my-repo on the local hub. Run scion use to see what is selected, and scion use --clear to forget it. See scion use.

Keeping the hub running

The server keeps running in the background until you stop it:

• scion server status shows whether it is running; scion server stop stops it.
• To start it at login, generate a service file with scion server install; see Workstation Server Mode.

When the hub is not running, commands say so:

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

Use scion --help and scion <command> --help to learn more about each command.

Next steps

• Working with Agents: the full agent lifecycle.
• Choosing a Mode: when to move from the workstation to a shared hub.
• Setting Up Telegram: message your agents from your phone.
• Upgrading from a release that ran agents without a hub? See the migration page.