docs: move Local Development to docs/local-dev.md with disclaimer

[chaodu-agent]

Summary

• Move the entire Local Development section (quick start + remote config) from README to docs/local-dev.md
• Add security disclaimer: OpenAB is designed for K8s with Pod-level isolation; running on bare host is not recommended for production
• README keeps a one-line link to the new doc

Context

Follows the decision to close PR #155 and issue #104 — OpenAB's security model relies on Kubernetes Pod isolation.

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: add security disclaimer for non-K8s deployments
• Source: docs: move Local Development to docs/local-dev.md with disclaimer #734
• Status: moved to PR-Screening
• Generated at: 2026-05-04T19:31:15.155Z
• Discord thread: https://discord.com/channels/1488041051187974246/1500942742845395040

Screening report

## Intent

PR #734 clarifies OpenAB’s deployment security assumptions in the README. It addresses a concrete operator-facing risk: users may assume host-native or non-containerized deployments are appropriate for production, even though OpenAB’s security model expects Kubernetes Pod isolation.

Feat

Docs improvement. The PR adds a short security disclaimer to the Local Development section of README.md, stating that OpenAB is designed for Kubernetes deployments with Pod-level isolation and that direct host execution without container isolation is not recommended for production.

Who It Serves

Primary beneficiary: deployers and agent runtime operators.

Secondary beneficiaries: maintainers and reviewers, because the README will better reflect the project’s intended security boundary and reduce repeated clarification around non-K8s deployments.

Rewritten Prompt

Update README.md to make OpenAB’s deployment security model explicit. In the Local Development section, add a concise warning that local host-native execution is intended for development only, and that production deployments should use Kubernetes or equivalent container isolation. Mention the expected isolation properties at a high level: Pod isolation, network policy, resource limits, and restricted filesystem access. Keep the wording brief, avoid overstating guarantees, and ensure it aligns with the project decision to close PR #155 and issue #104.

Merge Pitch

This is a low-risk documentation change that closes an important expectation gap for operators. It helps prevent unsafe production usage by making the intended isolation model visible where users are likely to read setup instructions.

Likely reviewer concern: wording should be precise enough to warn users without implying Kubernetes alone makes arbitrary workloads safe. The disclaimer should frame Kubernetes isolation as part of the supported deployment model, not as a complete security guarantee.

Best-Practice Comparison

OpenClaw principles relevant here:

• Explicit delivery routing: not directly relevant.
• Gateway-owned scheduling: not relevant.
• Durable job persistence: not relevant.
• Isolated executions: highly relevant. The README should state that OpenAB expects isolated execution environments for production use.
• Retry/backoff and run logs: not relevant.

Hermes Agent principles relevant here:

• Fresh session per scheduled run: indirectly relevant if OpenAB runs agents as isolated jobs, but not central to this docs change.
• Self-contained prompts for scheduled tasks: not relevant.
• Gateway daemon tick model: not relevant.
• File locking to prevent overlap: not relevant.
• Atomic writes for persisted state: not relevant.

The strongest best-practice alignment is with isolated execution as an explicit documented deployment assumption. This PR does not need to address scheduling, persistence, locking, or retry behavior.

Implementation Options

Option 1: Conservative README disclaimer
Add two sentences in the Local Development section explaining that local runs are development-only and production should use Kubernetes or equivalent isolation.

Option 2: Balanced security note with deployment distinction
Add a short “Security note” subsection under Local Development that distinguishes development, staging, and production expectations. Include examples of expected controls: Pod isolation, NetworkPolicy, resource limits, and read-only root filesystem.

Option 3: Broader deployment security documentation
Add the README disclaimer and create or update a dedicated deployment/security doc explaining supported production isolation assumptions, non-goals, and unsupported host-native production deployment.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative README disclaimer	High	Low	Medium	High	Medium	High
Balanced security note	High	Low-Medium	High	High	High	Highest
Broader deployment security doc	Medium	Medium	High	Medium	High	Medium

Recommendation

Use Option 2: add a short security note in the README that clearly separates local development from production deployment expectations.

It is still small enough to merge quickly, but more useful than a minimal disclaimer because it names the actual isolation assumptions reviewers care about. A broader security deployment document can be split into a follow-up if maintainers want a fuller production hardening guide.