Multi-project

One agent process serves one project. Multi-project is a console concern: the TUI and Desktop GUI connect to many agents from a local registry, while Web connects to one agent behind its own origin.

The registry

The TUI and Desktop read ~/.config/steelframe/projects.toml (XDG). It holds an optional default operator and a list of projects:

operator = "your-github-login"     # default for every project

[[projects]]
name = "makolate-stack"
url = "https://makolate.steelframe.chipcolate.com"
token = "v1.…"                      # bearer token for remote agents
operator = "your-github-login"      # overrides the default

[[projects]]
name = "local"
url = "http://127.0.0.1:7700"

Field	Purpose
name	Console label
url	Agent base URL
token	Optional bearer token for agents behind auth
operator	GitHub login for issue footers and audit

When no file exists, the registry defaults to a single local project at http://127.0.0.1:7700.

CLI

steelframe config          # first-run wizard, or add/update a project
steelframe config --list   # print configured projects (token redacted)

Add a remote agent non-interactively:

ssh root@HOST cat /root/steelframe-tui.token > /tmp/steelframe-tui.token
steelframe config \
  --name makolate-stack \
  --url https://makolate.steelframe.chipcolate.com \
  --token-file /tmp/steelframe-tui.token \
  --operator your-github-login

Keys in the TUI: [ / ] switch project, r refresh, q quit.

Operator identity

The console resolves the operator login and sends it as X-Auth-User, so GitHub issue footers say who filed them. Resolution order:

project operator → registry operator → STEELFRAME_OPERATOR → GITHUB_USER → gh api user → $USER → "operator"

The agent’s bearer token authenticates the connection; the identity headers are overwritten by the agent’s auth middleware when operator auth is enabled and verified.

Desktop vs TUI vs Web

Client	How it finds agents	Auth
TUI	projects.toml	Bearer token
Desktop	projects.toml	Bearer token; desktop OAuth paste flow
Web	URLs added in the UI, stored in localStorage as {name,url} only	Cookie / OAuth on the GUI origin

Web stores no tokens. Its agent list key is steelframe.gui.agents, and it probes an added origin with GET /api/status, accepting either a status JSON body or the operator-auth 401 challenge as proof the origin is an agent.

Web is one agent behind the GUI origin. The API is same-origin and CORS is credential-less, so a session cookie set on a remote agent’s origin is one the Web GUI can never read. Sign-in always targets the page origin; only the Desktop app uses a pasted bearer token for a remote agent.

Caution

Web cannot operate a remote agent across origins with cookies. Add the agent to the same origin (reverse proxy), or use Desktop/TUI with a bearer token.

Gotchas

• The registry is a console concern only. An agent does not read projects.toml.
• steelframe config --list redacts tokens.
• Token resolution is per project: a project without token connects unauthenticated to that agent.
• The Web agent list lives in browser localStorage, so it is per browser profile, not shared with Desktop.