Repository navigation
[Feature / Docs]: Production Headless Server Supervision & Bundled orca-server Skill #62
Description
[Feature / Docs]: Headless Server Onboarding, Production Supervision & Bundled orca-server Skill
What is this?
Official systemd supervision patterns and a bundled orca-server skill for keeping headless Orca servers reliable and debuggable by agents.
Why do I care?
| Problem | How This Solves It |
|---|---|
| Terminals Die on Restart | Documents systemd-run --user --scope so PTYs/agents survive systemctl restart. |
| Crash-Looping on Faults | Unit pins RestartPreventExitStatus=3 78 and KillMode=mixed to fail loudly instead of thrashing. |
| Lost Headless Docs | Restores and hardens setup docs removed in PR stablyai#26328. |
| Agent Blindspots | New orca-server skill lets agents triage their own host rather than failing blindly. |
| Zero-Jargon Onboarding | prompt.md asset allows operators to hand an AI agent one URL for a full, secure server install. |
Blast Radius
- Zero Binary Changes: No new dependencies, no core app modifications.
- Pure Additive: Only updates
docs/remote-servers.mdx, adds staticprompt.md, and bundles theorca-serverskill docs.
Testing
vitest: 39/39 passed (contracts:remote-servers-doc-contract.test.mjs,generate-bundled-skill-guides.test.mjs,skill-description-length.test.mjs)node --test: 16/16 passed (docs/site/tests/*.test.mjs)- Scripts:
generate-bundled-skill-guides.mjs --checkcleanly exits. - Functional: Live Docker container pairing verified over bridge network.
Related Issues and Upstream Context
- Replaces: Operational docs from PR Document headless Linux server setup stablyai/orca#6802 and PR docs(headless-server): add upgrade SOP for orca serve on Linux stablyai/orca#9575 (removed in PR docs: remove stale internal reference documentation stablyai/orca#26328).
- Complements: PR docs(headless): expand serve host agent-skills install guide stablyai/orca#13262 (
docs(headless): expand serve host agent-skills install guide). - Resolves: Issue [Bug] Can’t see Desktop’s localhost or html files in a tab on the mobile app? stablyai/orca#25962 (mobile loopback) and Issue worktree rm refuses after a daemon restart: PTYs stay registered on the dead daemon's socket stablyai/orca#26090 (dead PTY sockets).
- Companion: [Feature / Docs / Agent-Routing]: Deep Runtime Diagnostics Guide, CDP Telemetry, and
orca-diagnosticsSkill.
Architecture & Implementation Details
- Hardened systemd Unit: Copy-paste
/etc/systemd/system/orca-serve.servicepreventing PTY SIGKILLs viaKillMode=mixed. - Terminal Survival:
loginctl enable-linger+ daemon scoping. - Bundled Skill: Shipped via existing generator (
skill-guides/orca-server.md,references/systemd-supervision.md). - Agent Fetch Prompt:
/docs/agent-setup/prompt.mdallows zero-click setup via Claude/OMP.
[systemctl restart orca-serve.service]
│
▼ (KillMode=mixed sends SIGTERM only to main process)
[orca serve daemon] ─── shuts down cleanly
│
▼ (PTY daemon runs in sibling user scope)
[orca-daemon.scope] ─── SURVIVES! Terminals remain alive!
Activity