Runtime Broker

A Runtime Broker is the component of Scion that actually runs agents (containers or VMs). While a centralized Scion Hub manages metadata and agent configurations, you can register your own machine as a Runtime Broker to execute agents locally while still participating in your team’s Hub environment.

This is especially useful if you need agents to access local resources (like an intranet database, local files, or specialized hardware) or if you want to contribute compute power to your team’s projects.

Architecture

When you run a Runtime Broker connected to a Hub, your machine establishes a persistent WebSocket connection (a “Control Channel”) to the Hub.

The Hub acts as the control plane, but the actual execution (and the git worktrees) stay on your machine.

Registering Your Machine

To allow the Hub to dispatch agents to your machine, you must start a Runtime Broker and register it.

1. Start the Broker

You can start a standalone broker process in the background:

scion broker start

(Alternatively, if you run scion server start --workstation, a broker is automatically started alongside a local workstation server.)

2. Link to the Hub

Before the broker can receive commands, it must be registered with the Hub you are connected to. This establishes a secure trust relationship.

scion broker register

This command will securely exchange credentials with the Hub, linking your machine’s broker to your Hub user account.

3. Provide Compute for a Grove

Even after registration, your broker will not accept arbitrary agents. It only executes agents for specific Groves (projects) that you explicitly authorize it to serve.

Navigate to the directory of a project that is connected to the Hub, and run:

scion broker provide

This tells the Hub: “My local broker is now a provider for this specific Grove.” When anyone on your team starts an agent in this Grove and targets your broker, the agent will execute on your machine.

To verify which groves your broker is currently serving:

scion broker status

Security & Isolation

When you register your machine as a broker:

• Isolation: Every agent runs in its own isolated container and its own dedicated git worktree (.scion_worktrees/).
• No Source Code Sharing: The Hub does not store your source code. The broker simply creates local branches and commits.
• Safe Secrets: Sensitive API keys and environment variables managed in the Hub are injected directly into the agent container’s memory at runtime. They are not saved to your local disk.
• Mutual Authentication: All communication over the Control Channel uses HMAC-SHA256 signatures, ensuring that only the authorized Hub can send commands to your machine.

Stopping the Broker

If you want to stop accepting agent workloads from the Hub, you can simply stop the broker daemon:

scion broker stop

Agents that are currently running on your machine may be interrupted or left orphaned depending on their state.