eve runtime

Last verified: 2026-11-05 (repository inspection of tcpsystems/docs content and sibling tcpsystems/eve README/package metadata; no eve runtime mutated). Scope: tcpsystems/eve is the execution/runtime layer used by the estate. This page documents the operator mental model and safe checks. It does not deploy eve, change its models, or mutate production queues.

Ownership boundaries

Surface	Owner	Notes
eve runtime code, station behavior, session APIs, model-role config	tcpsystems/eve	Source of truth for implementation and runtime flags
acumen model access, keys, routing and cost ceilings	acumen/ops owners	eve calls acumen; key files and routing policy are external to eve code
Postgres/session storage and operational database state	Platform/data owners	Runtime state is durable; schema and data changes require migrations/tests in the owning repo
Podman/Quadlet/k3s/host service management	Fleet/runtime owners	Deployment units and host privileges are not managed from tcpsystems/docs
Product UIs (for example studio) that route work through eve	Product owners	UI behavior can lag behind runtime version; compare versions before diagnosing

Runtime overview

From the current eve README and docs surface summary:

• Stations. eve is described as a five-station durable runtime: intake, investigate, implement, review and decide.
• Durable queue/sessions. Work is tracked durably (for example pending/leased/final style state and session IDs), with resume after restart as a design goal.
• Scoped execution. The runtime is intended to run bounded commands for stations; docs should only claim the specific command scope that the current eve implementation verifies.
• Model access through acumen. eve uses OpenAI-compatible access to acumen, with keys read from paths (not embedded values) and per-role model selection.
• Runtime boot configuration. Role/model selection is resolved at runtime boot. The README documents flags such as EVE_STATION, EVE_STATION_ROUTING, and role-specific model/context/output overrides; treat them as operator-controlled deployment settings, not docs-time constants.

Prerequisites

• Access to the eve repository or its runtime environment, owned by the eve/fleet team (snapshot 2026-11-05).
• Node 24 for local eve development as documented by tcpsystems/eve (engines.node is 24.x and README notes host node differences).
• acumen credentials available by path in the target environment; never copy secret values into docs, shell history files committed to git, or evidence notes.
• Postgres connectivity and any required runtime secrets provided by the owning deployment. Database-first state belongs in Postgres via versioned migrations in the owning repo.

Verification checks

Use checks that match the environment you can access. Do not invent endpoints or mutate live sessions.

# Repository/build verification (in tcpsystems/eve, when dependencies are installed):
npm run typecheck

# Runtime log verification (deployment-specific; examples only):
journalctl -u <eve-unit> -n 200 --no-pager
# Look for boot-time role routing/model lines without exposing secrets.

# Session/API verification (only if the deployment exposes these paths):
curl -fsS -X POST http://127.0.0.1:<port>/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"input":"health check"}'

# Then follow the deployment's documented stream/read endpoint for that session ID.

# acumen dependency check (operator environment, key path handled outside docs):
curl -fsS https://ai.tcp.systems/v1/models -H "Authorization: Bearer $ACUMEN_KEY" | jq '.data | length'

Record the date, host, eve version/commit, and command exit codes when making an operational claim.

Failure handling

Symptom	First checks	Safe action
eve cannot reach acumen	Verify acumen base URL, key file path permissions, and curl /v1/models from the runtime host	Fix credential path or network routing in the owning deployment; do not embed keys in config files committed to git
Session does not resume	Check durable store connectivity, session ID, and runtime logs around lease/final transitions	Escalate to eve/runtime owners with session ID and timestamps; avoid manual queue edits in the deployment
Station uses unexpected model	Check boot logs for resolved role/model and deployment env (EVE_STATION, EVE_STATION_ROUTING, EVE_MODEL_*)	Change deployment configuration through the approved owner path; restart only if the owner runbook calls for it
Scoped command fails	Confirm the command is inside eve’s allowed execution scope and the target tool exists in the runtime image/host	Do not widen command scope from docs; treat scope expansion as a code/security change in tcpsystems/eve
UI behavior differs across hosts	Compare eve version/build on each host (for example scaleblade vs core)	Report version skew; do not document one host’s behavior as universal without a date and host label

Rollback and safety checks

• Roll back eve by redeploying the previous approved image/build and configuration through the fleet/runtime owner process. This repository does not carry those deploy commands.
• Keep model/provider credentials file-based and scoped; rotate by replacing the secret at the approved path and restarting/reloading as the eve deployment requires.
• If a change affects durable queue/session state, use the owning repository’s versioned migrations and tests. Do not make ad hoc production data edits.
• Before calling a runtime “healthy”, capture: service status, recent boot log line showing resolved station/model routing, and one successful non-destructive API or session check with date.

Integrator notes

• Treat eve as an execution dependency with version skew risk. Integrators should log the eve build/version and acumen request identifiers where available.
• Do not couple client behavior to undocumented station internals. Integrate against documented APIs and stable contracts owned by tcpsystems/eve.
• When a docs claim depends on live runtime behavior, label it as verified on a specific date and host.