Architecture & Safety

Arbiter is structured to enforce strong safety boundaries while orchestrating local operations. It behaves like a small development-focused SRE operator.

It deliberately avoids unrestricted shell access, arbitrary file editing, and unverified success claims.

Architecture Diagram

Browser UI       TUI / CLI       REST clients       MCP clients       A2A clients
    │                │                │                  │                 │
    └────────────────┴────────────────┴──────────────────┴─────────────────┘
                                  │
                         Interface adapters
                                  │
                    Agent and high-level orchestration
                                  │
        ┌───────────┬───────────┬───────────┬───────────┐
        │ Projects  │  Stacks   │   Ports   │  Docker   │
        ├───────────┼───────────┼───────────┼───────────┤
        │  Compose  │ Makefiles │  System   │  Safety   │
        └───────────┴───────────┴───────────┴───────────┘
                                  │
             Linux /proc + ss    Docker SDK    SQLite    project files

Business logic does not live in the UI, TUI, CLI, or API routes. Those layers translate requests into calls to shared domain services. This prevents one interface from bypassing safety rules or implementing behavior differently from another interface.

The application is a single Python process. It does not require Redis, Celery, Kafka, Kubernetes, or another background infrastructure service.

Core Domains

• ports: parses Linux ss, resolves processes through /proc, correlates Docker/Compose metadata, finds predictable free ports, and detects duplicate project claims and runtime port collisions.
• projects: bounded discovery below configured roots and a refreshable SQLite registry. No whole-filesystem scan occurs.
• stacks: multi-project environment profiles, 1-click context switching with dynamic .env override injection, port collision reconciliation, and topological DAG boot order orchestration.
• topology, system, and events: generate a live, typed machine graph from Compose/Docker metadata, /proc, ss, and Docker events; runtime state is not persisted as authoritative data.
• docker and compose: typed Docker SDK inspection, Compose label awareness, lifecycle operations, validation, and structured port editing.
• dockerfile, make, files, and impact: Dockerfile and Make intelligence, safe registered-project editing with backup/diff/rollback/undo, and deterministic pre-operation impact summaries.
• config_intelligence: cross-file port drift detection (.env vs compose.yaml vs .env.example), credential-safe missing env variable auditing, and visual diff dry-run time-travel state forecasting.
• safety, actions, and persistence: immutable persisted approvals, one typed action dispatcher, history, and mandatory verification outcomes.
• agent: deterministic intents plus LangChain v1's create_agent runtime, backed by LangGraph and restricted to the control plane's typed tools.
• api, cli, tui, and integrations: thin adapters over the same services.

Safety Model

Every state-changing operation has one of five risk levels:

An approval is a persisted object with a UUID, request ID, exact action name, exact serialized arguments, summary, risk, creation time, expiration time, and status.

Approving an action executes the stored payload. The agent cannot replace or modify arguments after approval. Expired, rejected, or previously approved requests cannot be reused.

Verification

Execution success and verification success are separate concepts. An action may return verification_failed even if its command completed.

Examples of verification include:

• checking a started/restarted container is running;
• checking a stopped Compose project has stopped containers;
• confirming a removed image or volume no longer exists;
• refreshing project configuration after a port change;
• checking the recreated service is running;
• checking the new host port has the expected owner;
• verifying stack readiness gates (tcp_port, http_get, docker_health) and checking measured endpoint latency.

Network readiness gates pass through a destination policy before any socket is opened. Connections use the validated resolved IP directly to prevent DNS rebinding. Loopback and registered Compose services are automatic; non-local targets require a persisted, revocable approval scoped to protocol, host, port, and resolved addresses. Redirect hops are independently checked, while link-local and metadata destinations are unconditionally denied.

Security Boundaries

The server binds to 127.0.0.1 by default. Important boundaries include:

• no arbitrary shell API;
• no generic filesystem read or write API;
• bounded automatic project scanning;
• explicit project registration;
• recognized Compose filename validation;
• fixed subprocess argument arrays with no shell=True;
• subprocess timeouts and captured output;
• bounded Docker log retrieval;
• exact container lookup with ambiguity rejection;
• secret-key redaction for names containing PASSWORD, SECRET, TOKEN, API_KEY, PRIVATE_KEY, or CREDENTIAL;
• persisted approval for risky actions;
• no automatic persistent-volume removal.