Skip to content

FIRST_RUN.md

Latest commit

 

History

History
266 lines (197 loc) · 10.4 KB

FIRST_RUN.md

File metadata and controls

266 lines (197 loc) · 10.4 KB
Raw

FIRST RUN

This guide is the shortest careful path from a source checkout to a running local profile.

Assumptions

  • you are operating in the Fedora-first runtime model
  • podman is available
  • rsync is available
  • the runtime root should be /srv/AbyssOS/abyss-stack

If you are starting from Windows, read WINDOWS_SETUP and use pwsh -File scripts/aoa.ps1 ... as the host entrypoint.

Fast path

From the source checkout:

export AOA_STACK_ROOT=/srv/AbyssOS/abyss-stack
export AOA_CONFIGS_ROOT=/srv/AbyssOS/abyss-stack/Configs

scripts/aoa-doctor
scripts/aoa-first-run --strict

That will:

  • check host and runtime prerequisites
  • create the runtime layout
  • sync repo-managed configs and docs
  • bootstrap public-safe runtime config templates
  • check the layout in strict bootstrap mode while still allowing missing secrets on that first pass

From a Windows host, the equivalent careful route is:

pwsh -File scripts/aoa.ps1 host-doctor
pwsh -File scripts/aoa.ps1 doctor --preset agent-full
pwsh -File scripts/aoa.ps1 first-run --strict

Then do the one thing it cannot do for you

Create the real secret-bearing files described in:

If the agent API layer is part of the selected profile or preset, verify that Configs/agent-api/return-policy.yaml was bootstrapped before launch.

Then validate the fully bootstrapped layout:

scripts/aoa-check-layout --strict

Optional but recommended: capture host facts and machine fit

Once the runtime roots exist, record both the public-safe and local-private host posture, then capture the bounded current-machine fit:

scripts/aoa-host-facts --mode public --write /tmp/reference-host.public.review.json
scripts/aoa-host-facts --mode private --write "${AOA_STACK_ROOT}/Logs/host-facts/latest.private.json"
scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"

Review the public artifact before commit. Do not commit the private artifact. Only refresh mechanics/machine-fit/parts/host-facts/examples/reference-host.public.json when you are intentionally updating the reviewed canonical Linux reference host snapshot. Refresh the private machine-fit record when kernel, firmware, container runtime, or validated local tuning changes.

Inspect the profile before launch

scripts/aoa-profile-modules --profile substrate
scripts/aoa-profile-endpoints --profile substrate

For absolute module paths:

scripts/aoa-profile-modules --profile substrate --paths

Deeper runtime truth before launch

After secrets exist, inspect what Compose actually sees:

scripts/aoa-render-services --profile substrate
scripts/aoa-render-config --profile substrate --write /tmp/abyss-substrate.rendered.yml

Treat the rendered config as potentially secret-bearing.

Bring up the first profile

scripts/aoa-up --profile substrate
scripts/aoa-wait --profile substrate
scripts/aoa-smoke --profile substrate

Move to richer profiles

Local worker runtime

This keeps the base substrate explicit and adds the canonical langchain-api -> llama.cpp worker path:

scripts/aoa-profile-modules --profile substrate --profile local-worker --paths
scripts/aoa-profile-endpoints --profile substrate --profile local-worker
scripts/aoa-render-services --profile substrate --profile local-worker
scripts/aoa-up --profile substrate --profile local-worker
scripts/aoa-smoke --profile substrate --profile local-worker
scripts/aoa-qwen-check --case exact-reply

Retained fallback gateway

This checks the old control lane intentionally, without making it part of the default substrate:

scripts/aoa-profile-modules --profile fallback-gateway --paths
scripts/aoa-profile-endpoints --profile fallback-gateway
scripts/aoa-render-services --profile fallback-gateway
scripts/aoa-up --profile fallback-gateway
scripts/aoa-smoke --profile fallback-gateway

Ollama warmup for this retained fallback lane is opt-in:

AOA_OLLAMA_WARMUP_ENABLED=true scripts/aoa-up --profile fallback-gateway

Optional workflow automation

This keeps n8n out of the default substrate while preserving an explicit route for workflow checks:

scripts/aoa-profile-modules --profile substrate --profile workflows --paths
scripts/aoa-profile-endpoints --profile substrate --profile workflows
scripts/aoa-render-services --profile substrate --profile workflows
scripts/aoa-up --profile substrate --profile workflows
scripts/aoa-smoke --profile substrate --profile workflows

Agent-facing runtime

This is the generic local agent path and defaults to the canonical llama.cpp worker path. Embeddings stay disabled unless an explicit backend overlay is added:

scripts/aoa-profile-modules --profile substrate --profile local-worker --paths
scripts/aoa-profile-endpoints --profile substrate --profile local-worker
scripts/aoa-render-services --profile substrate --profile local-worker
scripts/aoa-up --profile substrate --profile local-worker
scripts/aoa-smoke --profile substrate --profile local-worker
scripts/aoa-qwen-check --case exact-reply

Intel-aware runtime

This adds OVMS plus the Intel overlay module for the agent API. In the current reviewed posture, OVMS is used for the explicit embeddings lane while text stays on canonical llama.cpp. Broader Intel-serving experiments should stay in benchmark, machine-fit, or rollout lanes until separately reviewed:

scripts/aoa-profile-modules --profile substrate --profile intel-worker --paths
scripts/aoa-profile-endpoints --profile substrate --profile intel-worker
scripts/aoa-render-services --profile substrate --profile intel-worker
scripts/aoa-up --profile substrate --profile intel-worker
scripts/aoa-smoke --profile substrate --profile intel-worker
scripts/aoa-qwen-check --case exact-reply

On the first Intel launch, aoa-up links and reloads the source-managed user units before opening the OVMS activation sockets. It also retires an old Compose-owned ovms container for the same Compose project before the socket cutover, while the digest-pinned Quadlet image is allowed to pull only when it is absent. No separate pre-install step is required.

Use a preset instead of spelling the whole composition

scripts/aoa-preset-profiles --preset agent-full --paths
scripts/aoa-profile-endpoints --preset agent-full
scripts/aoa-render-services --preset agent-full
scripts/aoa-up --preset agent-full
scripts/aoa-smoke --with-internal --preset agent-full
scripts/aoa-qwen-bench --preset agent-full

Optional local model trials

The first-run path ends once the selected profile launches, waits, smokes, and passes its intended Qwen check. Local model trials, benchmark packets, model cards, and promotion candidates are separate inference-pilot work, not a required first-run health gate.

Use these package-owned routes after the runtime path is already healthy:

Those flows keep machine-readable runtime truth under ${AOA_STACK_ROOT}/Logs/local-ai-trials/ or ${AOA_STACK_ROOT}/Logs/runtime-benchmarks/, and may mirror curated Markdown summaries to /srv/Dionysus/reports/local-ai-trials/.

Optional bounded llama.cpp pilot

If you want to re-run the bounded llama.cpp pilot surfaces explicitly without changing the canonical runtime shape:

scripts/aoa-llamacpp-pilot run --preset intel-full

That pilot re-verifies the bounded llama.cpp launch path, starts the explicit pilot sidecar when needed, exposes langchain-api-llamacpp on 127.0.0.1:5403, and writes comparison artifacts under ${AOA_STACK_ROOT}/Logs/runtime-benchmarks/comparisons/. If the first locally resolved model candidate is rejected by llama.cpp on this machine, the pilot falls back to a locally cached curated bartowski candidate when one is already present. Use the same bounded lane for additive Intel 285H host-profile checks such as Gemma 4, Vulkan-first validation, or KV-cache candidate screening instead of treating those as instant defaults. Use LLAMACPP_PILOT for the full contract.

Compose optional layers manually

Agent runtime plus tools

scripts/aoa-profile-modules --profile substrate --profile local-worker --profile tools --paths
scripts/aoa-profile-endpoints --profile substrate --profile local-worker --profile tools
scripts/aoa-render-services --profile substrate --profile local-worker --profile tools
scripts/aoa-up --profile substrate --profile local-worker --profile tools
scripts/aoa-smoke --with-internal --profile substrate --profile local-worker --profile tools

Agent runtime plus tools plus observability

scripts/aoa-profile-modules --profile substrate,local-worker,tools,observability --paths
scripts/aoa-profile-endpoints --profile substrate,local-worker,tools,observability
scripts/aoa-render-services --profile substrate,local-worker,tools,observability
scripts/aoa-up --profile substrate,local-worker,tools,observability
scripts/aoa-smoke --with-internal --profile substrate,local-worker,tools,observability

If something feels wrong

Start with:

scripts/aoa-doctor
scripts/aoa-check-layout
scripts/aoa-status --profile substrate
scripts/aoa-logs --profile substrate

Then read: