Estate Console

Read-only control panel for a server estate: declare projects, repos, services, and domains in one registry, then continuously compare that declaration to live systemd, PM2, Docker, nginx, git, TLS, and optional GitHub Actions state.

Drift surfaces as a ranked issue list. There are no restart or deploy buttons. The access allowlist (auth.yaml) is the only write path.

This is the public product repository. The Meta-Layer production checkout and inventory stay in a separate private repo and are not published here.

Quick install

git clone https://github.com/Bridgit-DAO/estate-console.git
cd estate-console
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp registry.yaml.example registry.yaml
cp console.yaml.example console.yaml
cp modules.yaml.example modules.yaml
cp auth.yaml.example auth.yaml
# Optional: cp todos.yaml.example todos.yaml
# Edit registry.yaml paths, domains, and services for your box.
# Edit console.yaml estate_root and nginx/pm2 paths.
# Set CONSOLE_PROTECTED_HANDLE to match the locked handle in auth.yaml (default admin).

uvicorn server:app --host 127.0.0.1 --port 4100

Open http://127.0.0.1:4100/ – the first snapshot may take a minute while collectors probe your estate.

Bind to loopback only. Public access should go through nginx (see nginx-console.conf.example). Direct 127.0.0.1:4100 requests without X-Forwarded-For skip the cookie gate so local agents can read agent-drop; never expose port 4100 on a public interface.

Configuration files

File	Purpose
registry.yaml	Source of truth – projects, repos, services, domains
console.yaml	Host paths: nginx sites dir, PM2 dump, estate root, public URL
modules.yaml	Optional features: todos, agent drop, alerts
todos.yaml	Tracked backlog that suppresses matching warnings (optional)
auth.yaml	Web3Auth allowlist (copy from auth.yaml.example)

Example templates ship as *.example. Live yaml files are gitignored in this public repo so forks do not commit their estate by accident.

Environment overrides

Variable	Overrides
CONSOLE_CONFIG	Path to console.yaml
CONSOLE_MODULES	Path to modules.yaml
CONSOLE_REGISTRY	Path to registry.yaml
CONSOLE_TODOS	Path to todos.yaml
AGENT_DROP_DIR	Agent drop upload directory
CONSOLE_ESTATE_ROOT	Root for ~/… path display in UI
CONSOLE_NGINX_SITES	nginx sites-enabled directory
CONSOLE_PM2_DUMP	PM2 dump.pm2 path
CONSOLE_URL	Public console URL (alerts, links)
CONSOLE_AUTH	Path to auth.yaml
CONSOLE_SESSION_SECRET	Session cookie HMAC secret
CONSOLE_PROTECTED_HANDLE	Locked admin handle (default admin)
CONSOLE_CLI_TOKEN	Bearer token for the estate CLI (Access + remote); never print
CONSOLE_CLI_TOKEN_FILE	Token file path (default ~/.config/meta-console/cli.token)
WEB3AUTH_CLIENT_ID_DEVNET	Public Web3Auth client ID (optional override)

Alert credentials stay in a separate env file – never in the repo.

Modules

Toggle features in modules.yaml:

modules:
  todos:
    enabled: true
    path: todos.yaml
  agent_drop:
    enabled: true
    dir: agent-drop
  alerts:
    enabled: false
  custom: []

systemd (user unit)

Copy meta-console.service.example to your user systemd directory, edit paths, then:

loginctl enable-linger $USER
systemctl --user enable --now meta-console.service

nginx

Use nginx-console.conf.example: reverse proxy to 127.0.0.1:4100, keep /monitor/ping public, and rely on the Web3Auth allowlist for the rest. See docs/WEB3AUTH.md and docs/EXTERNAL-MONITORING.md.

CLI

Ship a first-party estate binary that wraps the localhost API:

ln -sf "$PWD/bin/estate" ~/bin/estate
estate health
estate status --json
estate drop list
estate access init-token   # prints path only; required for Access mutations

See docs/CLI.md. Loopback still allows status/drop without a token; /api/auth/users always needs the CLI bearer (or a browser admin session).

API

Endpoint	Description
GET /api/state	Full estate snapshot
GET /api/config	Title, paths, enabled modules
POST /api/refresh	Force snapshot rebuild
GET /api/todos	System todos (if enabled)
GET /api/agent-drop	Drop dir info (if enabled)
GET /healthz	Liveness (also via /monitor/ping on nginx)

Docs

• CLI (estate)
• Web3Auth allowlist
• System todos
• Agent drop
• External monitoring
• GitHub Actions monitoring
• Estate changelog

License

MIT – see LICENSE.