The four principles

Unibench is shaped by four product principles. They're load-bearing — features that conflict with them get pushed back, not bolted on.

1. The manifest is the source of truth

Every aspect of a project's local environment is in unibench.toml. Services, runtimes, dependencies, lifecycle hooks, seed scripts, secrets-by-reference. You can git diff what changed between yesterday and today; you can reproduce a colleague's setup by cloning their repo.

What this rules out:

  • "Click this button to enable Postgres" UI flows that mutate hidden state.
  • App-managed scratch directories that aren't a peer to the project folder.
  • One-shot "setup wizards" whose decisions you can't audit later.

Corollary: anything Unibench knows is something the manifest captures or something the orchestrator could re-derive from the manifest + filesystem.

2. Polyglot first

The first-class service types span Python, Node, Go, Ruby, Rust, and PHP ecosystems plus the five blessed data services (Postgres, Redis, Qdrant, Ollama, MinIO). A RAG project that mixes a Python indexer, a Node.js frontend, and a Go health-probe is the normal case, not an edge case.

The orchestrator's process and task_service types intentionally don't constrain the runtime — they wrap whatever binary the manifest names. mise-driven lockfile detection picks up the right Python / Node / Ruby version automatically when the project's lockfiles declare one.

3. The graph is the workspace

The dependency graph isn't a side view — it's the main UI surface. Every operational concern (start order, healthcheck retries, "why is API red?", "which service is blocking?") maps to a node or edge in that graph.

What this means for tooling:

  • Per-service inspection drawers (logs, env, ports, type-specific surfaces, Diagnose tab) hang off graph nodes.
  • The AI agent's read-only tool catalog is shaped around the graph (get_service_status, get_dependency_graph, get_service_logs).
  • The audit log scopes naturally to the open project's graph.

When a feature requires the user to leave the graph view, that's a signal we got the affordance wrong.

4. The AI agent is opt-in and read-only at v1

The agent (Anthropic / OpenAI / local Ollama via BYOK) is a diagnosis tool, not a control plane. v1 surfaces:

  • read-only tools over manifest + service state + logs + dependency graph
  • a structured response shape (summary / details / see_also / confidence) so the GUI can render usefully even when the model is unsure
  • per-response thumbs feedback (opt-in telemetry)

What the agent can't do in v1:

  • modify the manifest
  • start / stop / restart services
  • read or write secrets
  • send anything outside the chosen provider's endpoint

The "agent can write" path (decision 2.39 phase 2) is a v2 conversation with an audit-log surface and a per-action confirmation pattern.

These four principles are decision filters more than rules. When a new feature feels right but you can't tell which principle it serves, that's usually the sign to step back and reframe.