sophia-build

Rust coding harness forked from SpaceXAI Grok Build. Used for large autonomous ports and multi-hour tool work: native models drive sophia-build's own edit/shell/MCP/subagent stack under a short coding-agent prompt.

Sophia (Hermes) stays the identity and orchestrator. This TUI can either:

1. run native models through sophia-build tools (local / bare-model mode), or
2. talk to Sophia's Hermes backend (cloud mode: her SOUL, memory, Hermes-owned tools).

Canonical repo: SourceHut git@git.sr.ht:~krisyotam/sophia-build (FORGE.md).

---

Contents

• Switching modes: native models vs Hermes
• Quick start
• Authentication
• Models and BYOK
• Remote control (Tailscale)
• Hermes job bridge (worker direction)
• Extensibility
• Privacy
• Build
• Layout
• Docs
• Change log (sophia-build fork)
• Forge
• License

---

Switching modes: native models vs Hermes

This is the main control surface of the product.

                 sophia-build TUI  (/model …)
                        |
        +---------------+----------------+
        |                                |
   NATIVE MODE                      HERMES MODE
   bare model                       Sophia backend
        |                                |
   tools: this process              tools: Hermes on Sophia
   prompt: short coding             prompt: SOUL + memory
        |                                |
   heavy autonomous ports           conversation / her world

Switch to a native model

Catalog examples (see default_models.json and /model picker):

/model sonnet-5
/model kimi-k2.7-code
/model terra
/model opus-4.8

CLI:

grok -m kimi-k2.7-code
grok -p "port the auth module" -m sonnet-5 --always-approve

In this mode tools always run where the binary runs (desktop, laptop, or Sophia box if you SSH and run there). Prompt stays thin on purpose: this fork is the heavy tool, not a second SOUL.

Switch to Sophia (Hermes backend)

Point a catalog entry at Hermes' OpenAI-compatible API (Tailscale to the Sophia machine; do not expose the port publicly).

# ~/.grok/config.toml

[models]
# default = "sophia-hermes"   # optional: boot in Hermes mode
# default = "kimi-k2.7-code"  # or boot in native mode

[model."sophia-hermes"]
model = "sophia"                                    # id Hermes advertises on /v1/models
base_url = "http://100.78.242.77:8642/v1"         # Tailscale IP of Sophia box
name = "Sophia (Hermes)"
description = "Live Hermes: SOUL, memory, Hermes-owned tools"
env_key = "HERMES_API_KEY"                          # same value as API_SERVER_KEY on the box
api_backend = "chat_completions"
context_window = 200000

export HERMES_API_KEY=...   # from Sophia ~/.hermes/.env API_SERVER_KEY

Then in the TUI:

/model sophia-hermes

Back to native:

/model kimi-k2.7-code
# or
/model sonnet-5

Same session can switch mid-work with /model. Default for new sessions is whatever [models].default is.

Practical defaults

Honest limits today

• Native mode is complete: bare model + full sophia-build tool loop.
• Hermes mode as a model endpoint is usable for chat and Sophia-as-brain when the Hermes API accepts the request shape. True "Hermes owns every tool call and desktop is pure UI" is the hosted-agent direction (ACP / remote tools); until that is finished, treat Hermes mode as backend = Sophia, and native mode as backend = bare model + this harness's tools.
• Hermes hiring this harness (opposite arrow: she launches a headless coding job here) is already implemented: see Hermes job bridge.

Stack roles (do not merge)

---

Quick start

git clone git@git.sr.ht:~krisyotam/sophia-build
cd sophia-build
cargo build -p xai-grok-pager-bin --release
./target/release/xai-grok-pager

1. Auth (Grok OAuth and/or Codex OAuth and/or API keys).
2. /model … for native or Hermes as above.
3. Optional Nebius BYOK without xAI sub:

export NEBIUS_API_KEY=... TAVILY_API_KEY=... GROK_IMAGE_GEN=0
./deploy/nebius/setup.sh
grok -m kimi-k2.7-code

---

Authentication

Both Grok and Codex tokens can live in ~/.grok/auth.json under separate scopes.

---

Models and BYOK

Shipped roster (native): Sonnet (default), Fable (plan/judge), Opus, Terra, Composer, Grok 4.5, Kimi K2.7 Code (Nebius), Qwen2.5-VL, hidden grok-build compat.

Any OpenAI-compatible endpoint:

[model."my-endpoint"]
model = "provider/model-id"
base_url = "https://api.example.com/v1"
env_key = "MY_API_KEY"
api_backend = "chat_completions"
context_window = 128000

Quote dotted names: [model."kimi-k2.7-code"]. Pin aux models when off xAI (session_summary, image_description as full upstream IDs).

Nebius + Tavily profile: deploy/nebius/.

---

Remote control (Tailscale)

Phone steers a native-mode session on the host (not Hermes cloud).

/remote

Requires Tailscale on host + phone (same account). URL + QR on the tailnet. Tools stay on the host.

---

Hermes job bridge (worker direction)

Hermes launches this harness headless (not the TUI talking to her):

prod/hermes-bridge.sh --spec job.json

See 26-hermes-bridge.md.

---

Extensibility

Not Pi TypeScript extensions. Use:

Port Pi skills via [skills] paths = ["~/src/sophia/skills"]. Leave SOUL/Hermes tools on Hermes mode.

---

Privacy

Default: no bulk repo/trace upload, local-first telemetry off, secret redaction on model-bound reads, session export without xAI share. See 25-privacy.md.

---

Build

cargo build -p xai-grok-pager-bin --release   # target/release/xai-grok-pager
cargo check -p xai-grok-pager-bin

Rust via rust-toolchain.toml. protoc on PATH or bin/protoc. Prefer -p <crate> builds; full workspace is heavy. On disk-limited machines (e.g. Sophia), clean target/ when /home fills.

Root Cargo.toml is generated: edit per-crate manifests only.

---

Layout

---

Docs

Full user guide: crates/codegen/xai-grok-pager/docs/user-guide/

Especially: 02 auth, 04 slash (/remote), 07 MCP, 08–10 skills/plugins/hooks, 11 models, 14 headless, 15 ACP, 25 privacy, 26 Hermes bridge, 28 policy packs.

---

Change log (sophia-build fork)

Everything since the upstream open-source publish commit (c1b5909). Newest first.

2026-07-16 — Docs and dual backend story

2026-07-16 — Codex OAuth real endpoints

2026-07-16 — Tailscale /remote + Nebius BYOK

Verified on Sophia box: cargo check, remote_registered unit test, models lists Kimi + Qwen.

2026-07 — Compile/test on Sophia + test seams

2026-07 — Policy packs + forge policy

2026-07 — Privacy (Part 1) + models/bridges (Part 2 core)

Upstream base

Feature map (what you get vs stock Grok Build)

---

Forge

See FORGE.md. Upstream does not take external PRs (CONTRIBUTING.md).

Credits for absorbed work:

• /remote: daniel-farina/grok-build
• Nebius profile pattern: shivaylamba/grok-build-nebius

---

License

Apache-2.0 first-party (LICENSE). Third-party: THIRD-PARTY-NOTICES, tools crate notices, third_party/NOTICE.

---

Switching in one line: /model kimi-k2.7-code (or sonnet/terra/…) for native tools; /model sophia-hermes for Sophia's Hermes backend. Same TUI, different brain and tool owner.