Files

tegwick c12091c2eb Fixed and improved token tracking

2026-05-23 13:59:05 +02:00

5.3 KiB

Raw Blame History

State Hub Onboarding

This guide turns a new machine into a usable State Hub operator or collaborator environment. It covers local credentials, SSH reachability, Gitea access, and Claude Code MCP registration.

State Hub remains a coordination read/cache layer. Repo permissions, SSH access, and controlled tunnels are the first access boundary. OpenBao is the runtime secret authority for platform and workload secrets once its bootstrap ceremony is complete.

Quick Start

Clone the repo, then run the bootstrap script:

git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
cd ~/state-hub
make bootstrap-env

On a clean Ubuntu 24.04 machine, allow package installation explicitly:

make bootstrap-env ARGS="--install-missing"

For a remote machine that reaches State Hub through ops-bridge:

make bridges
make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000

Restart Claude Code after MCP registration.

Primary Operator: New Machine

Install minimal host prerequisites:

sudo apt-get update
sudo apt-get install -y git curl openssh-client make python3

Clone state-hub and any domain repo you expect to operate:

git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
git clone https://gitea.coulomb.social/coulomb/the-custodian.git ~/the-custodian

Run the bootstrap:
```
cd ~/state-hub
make bootstrap-env ARGS="--install-missing"
```
The script will:
- check required tools
- configure git credential.helper
- create ~/.ssh/id_ed25519 when missing
- print the public key for managed hosts
- create ~/.railiance_gitea.conf when you provide a Gitea token
- register the State Hub MCP server for Claude Code
- check State Hub API reachability
Authorize the SSH key on managed hosts. If password or existing key access is available, rerun:
```
make bootstrap-env ARGS="--authorize-ssh --skip-gitea --skip-mcp"
```
Default targets:
- tegwick@92.205.62.239 for Railiance01
- tegwick@92.205.130.254 for CoulombCore
Start or connect to State Hub:
```
make api
make mcp-http
```
If the hub is remote, use ops-bridge:
```
make bridges
```
Restart Claude Code and verify that state-hub appears in the MCP server list. In the first session, call get_state_summary() when MCP tools are available. If not, use:
```
cat .custodian-brief.md
curl -s "http://127.0.0.1:8000/workstreams/?status=active" | python3 -m json.tool
```

Domain Collaborator: New Person

Get a Gitea account with write access to the relevant domain repo.

Clone this repo and the domain repo:

git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
git clone https://gitea.coulomb.social/coulomb/<domain-repo>.git ~/<domain-repo>

Run the bootstrap:
```
cd ~/state-hub
make bootstrap-env
```
Send the printed SSH public key to the operator, or authorize it yourself if you already have host access:
```
ssh-copy-id -i ~/.ssh/id_ed25519.pub tegwick@92.205.62.239
```

Bring up the State Hub tunnel when direct local access is unavailable:

make bridges
make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000

Restart Claude Code, open the domain repo, and orient from the repo brief:
```
cat .custodian-brief.md
```
Contribute work through repo-backed workplans. A new workplan lives under workplans/ and follows ADR-001. The hub indexes files; the files remain authoritative.

Credential Helper Choices

make bootstrap-env configures Git credentials only when no global helper is already set.

Default behavior:

use libsecret when the helper exists
otherwise use credential.helper=cache --timeout=3600

For headless hosts where a persistent plaintext helper is acceptable:

make bootstrap-env ARGS="--git-helper store --allow-plaintext-store"

Prefer SSH remotes or a keyring-backed helper for normal operator machines.

Gitea Token File

Some Railiance scripts read ~/.railiance_gitea.conf:

GITEA_URL="http://92.205.130.254:32166"
GITEA_USER="<user>"
GITEA_TOKEN="<token>"

Required token capabilities depend on the action:

repo creation needs read:user and repository write/admin scope
package publishing needs package write scope
inventory reads need repository read scope

The bootstrap script writes this file with mode 0600 and does not print the token.

MCP Registration

Local registration:

make register-mcp

Tunnel registration:

make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000

The current State Hub MCP transport is SSE. The old .mcp.json/stdio flow is legacy; use make mcp-http to run the SSE service on 127.0.0.1:8001.

Verification Checklist

Run these checks after bootstrap:

git config --global --get credential.helper
test -f ~/.ssh/id_ed25519.pub
test -f ~/.railiance_gitea.conf
curl -fsS http://127.0.0.1:8000/state/health || curl -fsS http://127.0.0.1:18000/state/health
make register-mcp DRY_RUN=1

Then restart Claude Code and confirm that the state-hub MCP server is available.

5.3 KiB Raw Blame History