Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
e6ee4ac
Plan M017 managed client credentials corrective
dbowm91 Oct 15, 2026
4f3f6e0
Plan M018 local operator status corrective
dbowm91 Oct 15, 2026
9b35316
Plan M019 secure login GET and solo LAN corrective
dbowm91 Oct 15, 2026
1994fe3
Plan M020 managed state and headless administration
dbowm91 Oct 15, 2026
19268b2
Plan M021 small-team default provisioning
dbowm91 Oct 15, 2026
6a1de9d
Plan M022 hard budget client compatibility
dbowm91 Oct 15, 2026
a0aedd8
Plan M023 small-team short-window admission fairness
dbowm91 Oct 15, 2026
41ff19f
Plan on-prem concurrency M002 ordinary-server small-team baseline
dbowm91 Oct 15, 2026
576d20d
Clarify solo SBC versus on-prem team-server target
dbowm91 Oct 15, 2026
6c4f0be
Clarify phase 5 operational and hardware acceptance
dbowm91 Oct 15, 2026
98142c5
Reconcile on-prem post-merge roadmap and M017-M023 dependencies
dbowm91 Oct 15, 2026
38e46b4
Separate solo SBC baseline from ordinary-server team qualification
dbowm91 Oct 15, 2026
24a5775
Register post-merge M017-M023 and ordinary-server M002 handoffs
dbowm91 Oct 15, 2026
cf64a86
Clarify M016 as historical pre-merge hold after PR7 landing
dbowm91 Oct 15, 2026
b837a6f
Activate on-prem access plan 017
dbowm91 Oct 15, 2026
d726bce
Reconcile managed client credentials
dbowm91 Oct 15, 2026
218df45
Clarify personal credential delivery
dbowm91 Oct 15, 2026
f83af45
Start closing on-prem access plan 017
dbowm91 Oct 15, 2026
cdfb6fa
Add ordinary-server qualification corpus
Oct 15, 2026
af735f1
Close M002 qualification tooling conditionally
Oct 15, 2026
c5167aa
Retire shared key CLI after bootstrap
dbowm91 Oct 15, 2026
5ab7586
Close on-prem access plan 017
dbowm91 Oct 15, 2026
adc7278
Activate on-prem access plan 018
dbowm91 Oct 15, 2026
0a2a7e7
Correct keyless remote export regression
dbowm91 Oct 15, 2026
2355012
Record keyless export test correction
dbowm91 Oct 15, 2026
8e2b66a
Add local operator status readback
dbowm91 Oct 15, 2026
dee2175
Start closing on-prem access plan 018
dbowm91 Oct 15, 2026
3be5d83
Prove keyless local status CLI readback
dbowm91 Oct 15, 2026
49d2c4e
Close on-prem local status corrective plan 018
dbowm91 Oct 15, 2026
b437524
Activate on-prem login transport plan 019
dbowm91 Oct 15, 2026
b18a561
Gate browser login on trusted transport
dbowm91 Oct 15, 2026
0bf9c11
Start closing on-prem login plan 019
dbowm91 Oct 15, 2026
cdfc4f5
Close login transport plan and unblock headless admin
dbowm91 Oct 15, 2026
c8d8d0e
Activate headless administration plan 020
dbowm91 Oct 15, 2026
8a875a1
Implement headless member lifecycle and managed transition
dbowm91 Oct 15, 2026
c0828f9
Start closing headless administration plan 020
dbowm91 Oct 15, 2026
c32f141
Close headless administration plan and unblock defaults
dbowm91 Oct 15, 2026
2e99cdd
Activate default member provisioning plan 021
dbowm91 Oct 15, 2026
b76d359
Implement default member policy provisioning
dbowm91 Oct 15, 2026
4db0ead
Start closing default member policy plan 021
dbowm91 Oct 15, 2026
ee563be
Verify default member CLI workflow
dbowm91 Oct 15, 2026
3f1ca54
Cover member default policy transition race
dbowm91 Oct 15, 2026
aa59f1d
Close default member policy plan 021
dbowm91 Oct 15, 2026
1406f3c
Activate hard-budget compatibility plan 022
dbowm91 Oct 15, 2026
dee65ae
Improve hard budget agent compatibility
dbowm91 Oct 15, 2026
45f43e9
Start closing hard budget compatibility plan 022
dbowm91 Oct 15, 2026
2ce15a0
Close hard budget compatibility plan 022
dbowm91 Oct 15, 2026
ed8b38b
Integrate ordinary server qualification evidence
dbowm91 Oct 15, 2026
e284b45
Add recovery evidence to ordinary-server qualification
Oct 16, 2026
7b5eae3
Fix direct ordinary-server runner invocation
Oct 16, 2026
1c3d15b
Keep qualification budget above verification requests
Oct 16, 2026
2ce1bc4
Tie M002 recovery checks to managed identity
Oct 16, 2026
44166c2
Resume incomplete ordinary-server matrices safely
Oct 16, 2026
63268e1
Summarize ordinary-server latency and storage facts
Oct 16, 2026
f7343eb
Complete ordinary server qualification evidence tooling
Oct 16, 2026
deda832
Close ordinary server baseline and unblock M023
Oct 16, 2026
3722ae6
Activate M023 short-window fairness controls
dbowm91 Oct 16, 2026
84482e9
Implement bounded short-window admission fairness
dbowm91 Oct 16, 2026
472bef9
Start closing M023 short-window fairness controls
dbowm91 Oct 16, 2026
3776e41
Close M023 with Linux performance condition
dbowm91 Oct 16, 2026
f08a760
Skip legacy key generation after admin bootstrap
Oct 16, 2026
83c0779
Measure M023 short-window throttling
Oct 16, 2026
e68a402
Close M023 with ordinary Linux qualification
Oct 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,10 @@ eggpool update 0.8.0 # exact historical-version switch
eggpool serve
eggpool status

export EGGPOOL_API_KEY="$(eggpool getkey)"
# For a managed installation, create a personal credential for this user and
# set its one-time value in the client environment:
eggpool users token USER --show-secret
export EGGPOOL_API_KEY='<personal-token-shown-once>'

# Liveness / readiness (no key needed)
curl http://127.0.0.1:11300/v1/healthz
Expand All @@ -90,11 +93,10 @@ curl -H "Authorization: Bearer $EGGPOOL_API_KEY" \
http://127.0.0.1:11300/v1/chat/completions
```

Inference (`/v1/*` except `/v1/healthz` and `/v1/readyz`), integration
(`/api/integrations/*`), and status endpoints (`/api/status`,
`/api/stats/runtime`, `/api/stats/update`) require the server key as
`Authorization: Bearer <key>` (OpenAI-style) or `x-api-key: <key>`
(Anthropic-style); without it they return `401`. To pin a provider, qualify
Managed inference and integration requests use the caller's personal token as
`Authorization: Bearer <token>` (OpenAI-style) or `x-api-key: <token>`
(Anthropic-style). Legacy, pre-bootstrap installs may continue using the
shared server key until migration; it does not grant managed-user access. To pin a provider, qualify
the model as `model/provider` (e.g. `"gpt-4o/openai"`); `eggpool accounts
explain --model <id>` shows per-account eligibility. Full endpoint list:
[API reference](docs/api-reference.md).
Expand All @@ -108,12 +110,18 @@ eggpool configsetup claude-code
eggpool configremote codex # secret-free remote profile for other machines
```

Generated configs reference `EGGPOOL_API_KEY` without embedding the key (`export EGGPOOL_API_KEY="$(eggpool getkey)"`). See [Agent Configuration](docs/agent-configuration.md) for all targets, the managed `--apply`/`--sync`/`--check`/`--remove` lifecycle, remote profiles, and the transactional `eggpool-connect` desktop helper.
Generated configs reference `EGGPOOL_API_KEY` without embedding the key. Set it to a personal token from `eggpool users token USER --show-secret`; `eggpool getkey` is only for legacy installs. See [Agent Configuration](docs/agent-configuration.md) for all targets, the managed `--apply`/`--sync`/`--check`/`--remove` lifecycle, remote profiles, and the transactional `eggpool-connect` desktop helper.

## Dashboard & LAN Access

By default EggPool binds `0.0.0.0:11300` and serves a public read-only dashboard at `http://<lan-ip>:11300/`. To share with desktops on your LAN, set `[integrations].advertise_base_url = "http://<lan-ip>:11300/v1"`, run `eggpool rehash` (advertised URL is live-reloadable profile output; it never changes the listen socket), then export a profile with `eggpool configremote codex`. Lock it down with `[server].host = "127.0.0.1"` (local only) or `eggpool dashboard public --off` (key required on the dashboard too). See [Firewall](docs/firewall.md).

Browser password sign-in is shown only over loopback or trusted HTTPS proxy
transport. A remote plaintext HTTP visit to `/login` receives an explanation
without a username or password form. For a solo headless device, use SSH port
forwarding to loopback; teams should use an operator-managed HTTPS proxy or
VPN. LAN inference tokens remain a separate API transport choice.

## CLI Essentials

| Command | Description |
Expand Down
16 changes: 11 additions & 5 deletions architecture/deep-dive-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,20 @@ Back to [Architecture](README.md). See also the review index in [overview.md §1

## Control socket

`rust/src/operations/control.rs` owns the Unix-domain JSON protocol, one request per connection, `PROTOCOL_VERSION = 1`, `MAX_REQUEST_BYTES = 65_536`, `CONTROL_TIMEOUT = 30s` (`rust/src/operations/control.rs:31-34`):
`rust/src/operations/control.rs` owns the Unix-domain JSON protocol, one request per connection, `PROTOCOL_VERSION = 1`, `MAX_REQUEST_BYTES = 65_536`, `CONTROL_TIMEOUT = 30s`:

- `ControlRequest` (`reload`, `parse_frame`): the only accepted command is `reload_config` (`control.rs:173-177`), with an optional 64-char lowercase hex `validated_digest`. Depth pre-checks bound parsing before DOM allocation.
- `ControlResponse` (`error`, `from_reload`): bounded metadata-only outcomes (stage, generation, changed sections, restart-required paths, retirement flag); no secrets, bodies, or provider error text.
- `ControlClient` (`new`, `with_timeout`, `reload`, `send`): typed one-shot client used by `rehash`.
- `ControlRequest` (`reload`, `readback`, `parse_frame`): accepts `reload_config`, `read_status`, and `read_runtime_status`. Reload alone accepts an optional 64-char lowercase hex `validated_digest`; readback requests reject parameters. Depth pre-checks bound parsing before DOM allocation.
- `ControlResponse` (`error`, `from_reload`, `with_payload`): bounded reload metadata or sanitized status projections; no secrets, bodies, or provider error text. Readback is capped below the 65,536-byte frame limit.
- `ControlClient` (`new`, `with_timeout`, `reload`, `read_status`, `send`): typed one-shot client used by `rehash`, `status`, and `runtime-status`.
- `ControlServerHandle` (`path`, `close`) via `start`: sole process-local listener, socket mode `0o600`, runtime dir `0o700`, stale-socket identity checks; `close` unlinks only its own socket while a retained reload may still finish.

The control plane carries reload only. `runtime-status` is not a control command: `runtime.rs::fetch_runtime_status` (`rust/src/runtime.rs:2759-2761`) reads the authenticated `GET /api/stats/runtime` projection (`server/health.rs::runtime_status` at `rust/src/server/health.rs:129`), which renders `RuntimeDiagnosticsSnapshot`.
The same-user local operator reads status through this socket after identity
initialization; HTTP `/api/status` and `/api/stats/runtime` keep their existing
browser-session authorization. The socket resides in a private runtime
directory and is mode `0o600`, so possession of the OS-owned local identity is
the authority. Missing/stale sockets are reported as unavailable; malformed
or oversized protocol responses fail closed. Member tokens never gain status
or runtime-diagnostics access.

## Config mutation

Expand Down
2 changes: 1 addition & 1 deletion architecture/deep-dive-database.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Commit/rollback ambiguity fails closed: body failure maps to `Transaction`/`Sqli

## Migrations

Migrations are embedded from `rust/assets/db/migrations/` (zero-padded `0001_*.sql`…`0062_*.sql` = versions 1–62) with `checksums.json` (`files` map, 62 entries), validated by `MigrationRunner::validate_embedded_checksums` before any database use. Migration 55 adds downstream identity and credential storage without repurposing upstream `accounts`; migration 56 adds browser sessions and CSRF digests; migration 57 adds user/auth-epoch attribution to request rows and selector-parent linkage; migration 58 adds local model-policy profiles, exact rules, per-user overrides, instance denials, and a monotonic policy revision; migration 59 adds user budget rules, request holds, attempt usage, audit, and bounded user/model/time rollups; migration 60 adds bounded secret-free administrative audit events; migration 61 adds the hard/estimated enforcement mode, worst-case hold facts, and price provenance to the budget tables; migration 62 adds the instance-global budget scope (rules, request holds, per-model usage buckets, audit, policy-revision triggers) with no user reference. Schema history is never rewritten or renumbered. `MigrationRunner::run` keeps the `_migrations` ledger, rejects unknown versions and ledger-name mismatches, refuses read-only migration, and applies all pending migrations in one atomic transaction. Restore validation additionally checks the staged ledger against this inventory.
Migrations are embedded from `rust/assets/db/migrations/` (zero-padded `0001_*.sql`…`0063_*.sql` = versions 1–63) with `checksums.json` (`files` map, 63 entries), validated by `MigrationRunner::validate_embedded_checksums` before any database use. Migration 55 adds downstream identity and credential storage without repurposing upstream `accounts`; migration 56 adds browser sessions and CSRF digests; migration 57 adds user/auth-epoch attribution to request rows and selector-parent linkage; migration 58 adds local model-policy profiles, exact rules, per-user overrides, instance denials, and a monotonic policy revision; migration 59 adds user budget rules, request holds, attempt usage, audit, and bounded user/model/time rollups; migration 60 adds bounded secret-free administrative audit events; migration 61 adds the hard/estimated enforcement mode, worst-case hold facts, and price provenance to the budget tables; migration 62 adds the instance-global budget scope (rules, request holds, per-model usage buckets, audit, policy-revision triggers) with no user reference; migration 63 adds one audited, instance-local default member profile without changing existing assignments. Schema history is never rewritten or renumbered. `MigrationRunner::run` keeps the `_migrations` ledger, rejects unknown versions and ledger-name mismatches, refuses read-only migration, and applies all pending migrations in one atomic transaction. Restore validation additionally checks the staged ledger against this inventory.

`users`, `user_credentials`, and `user_access_state` hold usernames, password
hashes, downstream roles, token digests, scopes, and explicit transition state.
Expand Down
7 changes: 4 additions & 3 deletions architecture/deep-dive-integrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,10 @@ OpenCode are the exceptions: Codex TOML contains only
`env_key = "EGGPOOL_API_KEY"` and OpenCode JSON uses
`{env:EGGPOOL_API_KEY}` interpolation, so both snippets are non-secret, print
by default, and `--print-secret` does not alter them. The delivery hints tell
operators to set that environment variable and use `eggpool getkey` to
retrieve the current value. Configsetup never executes a shell or writes a
shell profile.
operators to set that environment variable to the user's personal token.
`eggpool getkey` remains a legacy-installation command and does not issue a
managed-user credential. Configsetup never executes a shell or writes a shell
profile.

## Provider-neutral agent projection

Expand Down
9 changes: 9 additions & 0 deletions architecture/deep-dive-observability.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ bodies, cache keys, token values, or raw upstream error prose.
| Streaming-outcome counters | `rust/src/coordinator/streaming/diagnostics.rs` (`StreamDiagnostics`, `StreamDiagnosticEvent`) |
| Operator rollups, explain plans, dashboard queries | `rust/src/operations/operator.rs` over `rust/src/db/` repositories |

The offline M002 host-capacity corpus is owned by
`scripts/qualification_ordinary_server.py` and its Q008 runner. It records
sanitized host/build identity, storage class, host I/O pressure, response
percentiles, and durable settlement for synthetic loopback workloads. These
artifacts are qualification evidence, not runtime telemetry or a production
capacity promise. One opt-in 60-request SQLite publication diagnostic records
gate wait/hold phases for this target; those samples are supplementary and are
not implied by, or substituted for, the per-cell host I/O counters.

See [Metrics](deep-dive-metrics.md) for the coalescer contract (including
the M002 ownership paragraph, which is authoritative) and
[Dashboard](deep-dive-dashboard.md) for the HTTP/CLI presentation layer.
Expand Down
12 changes: 11 additions & 1 deletion architecture/deep-dive-request-lifecycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,16 @@ adapts the response, and converges durable state.
extractor: it acquires a `GenerationLease`, reads the live
`server.max_request_body_bytes`, and enforces it while the body streams.
`is_inference_path()` covers exactly the four public inference routes.
- The same middleware consults the process-local short-window fairness
limiter after authentication and generation acquisition but before reading
the body or reserving durable user/global budget. It keys buckets by
authenticated user ID, shares allowance across that user's credentials,
applies optional per-principal/global 60-second token buckets, and bounds
retained principal state. It never queues, writes SQLite, or changes
provider routing. State resets on restart; absent rules allocate no bucket.
Throttles are 429 with `Retry-After` and
`short_window_rate_limited`; successful admissions expose bounded remaining
allowance headers.
- Declared `Content-Length` above the live limit is rejected before polling
(413); malformed `Content-Length` is 400. A 32 KiB initial
`RawBodyReservation` is taken against `effective_ceiling()` =
Expand Down Expand Up @@ -147,7 +157,7 @@ adapts the response, and converges durable state.
caller's explicit compatible output cap (`max_tokens`/`max_completion_tokens`
on chat, `max_output_tokens` on Responses/compact, `max_tokens` on Anthropic
Messages) converted at the operator-configured provider tariff — and deny
with `BudgetNotEnforceable` (429, no upstream submission) when unbounded,
with `BudgetNotEnforceable` (429, no upstream submission) when unbounded,
unpriced, or overflowing. The initial hard hold covers two attempt
equivalents (concrete attempt plus unattributed selector overhead); retries
extend by one equivalent after re-checking. Observed provider usage above
Expand Down
22 changes: 22 additions & 0 deletions architecture/deep-dive-security.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,22 @@ values fall back to the proxy peer. No other forwarded header establishes
trust.
`security.allow_insecure_web_auth` is an explicit development override and
emits a startup warning.

The local operator CLI uses the data-directory owner's filesystem authority.
`users add` commits a member, an explicit or configured default initial profile,
the transition from
`admin_initialized` to `managed`, and audit entries in one transaction; a
failed profile assignment leaves the original state intact. The explicit
`users enable-managed` path uses the same transition helper and records its
own audit event. A remaining configured shared key is rejected after
identity initialization, and `dashboard.public` cannot expose managed routes;
removing those stale config values is cleanup, not a precondition for the
atomic cutover. Default member profile selection is audited and revisioned,
affects only future member creation, and does not alter existing assignments.
Clearing restores deny-by-default for future unassigned members. No budget
template is copied; budget scopes remain independently configured. Disabling a user revokes sessions and tokens and advances the
auth epoch. Re-enabling does not un-revoke credentials, and the last active
administrator remains protected.
Session-authenticated responses carry `Cache-Control: no-store, max-age=0` so
account and administration HTML containing identity, budget, or CSRF data is
not retained by shared or browser caches. Privileged browser mutations also
Expand All @@ -80,6 +96,12 @@ Failed personal-token lookups use a 256-entry, one-second negative cache keyed
by token digest. Successful token lookups are not cached, so revocation takes
effect on the next request.

Optional short-window fairness uses only the authenticated principal's
database-owned user ID; credentials and request headers cannot choose a bucket.
The process-local table is capacity-bounded, stale entries are reclaimed only
after the full refill window, and a full table fails closed for new principals.
No token, prompt, body, IP, or provider outcome is retained in limiter state.

## Headers, bodies, and redaction

Provider credentials are added only at dispatch-header construction. Incoming
Expand Down
Loading
Loading