> For the complete documentation index, see [llms.txt](https://docs.layeronecloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layeronecloud.com/ai/repositories.md).

# Repository map

Which repository owns what, where each tree lives, and the command that verifies a change.

The LayerOne platform, Network Monitor, standalone monitoring agents, and pve-microvm each have a code repository. GitBook owns their feature reference, setup, deployment, and operational guides; this repository is its automatic export.

## LayerOne — `LayerOne-LLC/LayerOne` <a href="#layerone--layerone-llclayerone" id="layerone--layerone-llclayerone"></a>

The Django monolith. One codebase, three audiences: the public site at `/`, the client portal at `/client/`, and the operations console at `/console/` (tickets live there, not under `/client/`).

Railway, Docker, PostgreSQL, Redis and Celery in production. Locally: SQLite, LocMem cache, eager Celery, console email and dry-run provisioning.

```
apps/
  accounts/        Identity, sign-in, access modes, staff roles, MFA, passkeys
  api/             Client API, API keys, request metering
  billing/         Catalog, wallet, orders, Stripe/PayPal, provisioning,
                   Proxmox, IPAM, VMs, organizations and tenants, statements
  webhosting/      Shared-hosting catalog, CloudLinux nodes, jobs, DNS, mail
  paas/            Application platform: apps, builds, releases, microvm
                   placement, private projects, router config, GitHub deploys
  core/            Dashboards, public status, health, email transport, agent API
  marketing/       Public site, CMS pages, blog, looking glass, promo pages
  sites/           Multi-site configuration and template context
  status_pages/    Public status-page data model
  tickets/         Client and operations ticketing
  incidents/       Incident lifecycle and public publication
  infrastructure/  Device inventory and topology
  monitoring/      Checks, outages, uptime, remote agents
  audit/           Append-only operations audit trail
  campaigns/       Lifecycle and marketing email
  referrals/       Refer-a-friend and affiliate programs
  recordings/      First-party session replay of the public site and /client/
  network_alerts/  LayerOne Aegis: DDoS incidents, telemetry, port scans
  assistant/       Chat dock, live handoff, help-center knowledge index
agents/web-server/ The CloudLinux node agent — a separate deployable
config/settings/   base.py (shared), local.py (dev default), production.py
scripts/           Smoke, navigation-audit, startup and asset-build scripts
static/, templates/
```

`config/urls.py` composes the routes. Django admin is at `/console/django-admin/`. `/r/`, `/email/`, `/api/`, `/docs/` and `/downloads/` mount **ahead of the marketing CMS catch-all**, or a CMS page at one of those paths would swallow the feature.

### Verifying a change <a href="#verifying-a-change" id="verifying-a-change"></a>

macOS and Linux use `.venv/bin/python`; Windows uses `.\.venv\Scripts\python.exe`. The test runner already sets parallelism, the MD5 hasher and the migration template — **pass no flags**.

```sh
.venv/bin/python manage.py test <narrowest label that covers the change>
```

Escapes: `--parallel 1` for debugging or `--pdb`, `--fresh-db` for a corrupt template. Do not create `.env` from `.env.example` to run tests — `DEBUG=true` breaks `test_base_defaults_*`. If the change adds a model field, also run `manage.py makemigrations --check --dry-run`.

Small work — copy, labels, CSS, docs, one-line fixes — needs no tests. See [Testing and QC](/platform/testing.md) for the suite's 500-test cap and what belongs in it.

## The node agent — `agents/web-server/` inside the LayerOne repo <a href="#the-node-agent--agentsweb-server-inside-the-layerone-repo" id="the-node-agent--agentsweb-server-inside-the-layerone-repo"></a>

The OS interface for a CloudLinux hosting node. The Django repo two directories up is the control plane and the source of truth; this tree holds **no business policy**. Roughly 47 typed operations: apply them, report what happened.

A previous version reached 142k lines for this surface and was rewritten. **Growth is a stop signal.**

```
layerone/api.py         unprivileged HTTPS; validates and enqueues
layerone/runner.py      privileged reconciler; the only OS writer
layerone/store.py       SQLite, ownership boundary intact
layerone/registry.py    the single declaration of every operation
layerone/schema.py      declarative validation
layerone/provider.py    privileged execution through a fixed tool table
layerone/blobs.py       the one content channel
layerone/operations/    handlers, one module per panel feature
layerone/tenant/        workers that run as the tenant inside CageFS
```

Verify from `agents/web-server/`, not the Django root:

```sh
python3 -m unittest discover -s tests -t . -v
```

Do not mock the store, filesystem, lock or transaction. Ownership changes need a cross-tenant no-state-change test. See [Node agent architecture](/node-agent/architecture.md).

## L1 Network Monitor — `LayerOne-LLC/Network-Monitor` <a href="#l1-network-monitor--layerone-llcnetwork-monitor" id="l1-network-monitor--layerone-llcnetwork-monitor"></a>

Network observability for Proxmox VE 9 clusters. A Rust sensor on every traffic-carrying node aggregates libpcap observations locally and sends bounded telemetry over outbound HTTPS to a separate Django control plane. Each host uses a revocable, host-scoped API key; the control plane stores only the key hash.

```
agent/    Rust/libpcap Proxmox sensor and local durable spool
server/   Django ASGI control plane, ingestion worker, APIs and UI
proto/    Versioned sensor-to-server telemetry contract
deploy/   Local Docker Compose stack and Proxmox systemd packaging
```

Python 3.13 and PostgreSQL in production; SQLite and an in-memory channel layer are supported only by the test settings.

```sh
.venv/bin/python server/manage.py test monitoring --settings=l1monitor.test_settings
node --test server/monitoring/tests/*.test.js
cargo test --manifest-path agent/Cargo.toml
```

See [Trust and data flow](/network-monitor/architecture/trust-and-data-flow.md) for the boundary between the sensor and the control plane.

## Documentation — `LayerOne-LLC/Documentation` <a href="#documentation--layerone-llcdocumentation" id="documentation--layerone-llcdocumentation"></a>

The automatic Git Sync export of all LayerOne feature and developer documentation. Remote: [LayerOne-LLC/Documentation](https://github.com/LayerOne-LLC/Documentation). Local checkout: `../LayerOne Docs` relative to the LayerOne repository root. GitBook publishes the **LayerOne LLC Docs** site at [docs.layeronecloud.com](https://docs.layeronecloud.com).

Read and author reference pages through the connected GitBook MCP. Create, edit, verify, and merge GitBook change requests when features are added or changed. Git Sync exports published content, navigation, assets, and site configuration to this repository automatically. Do not manually edit or push synchronized files. See [Contributing](/contributing.md).

## Standalone agents — `LayerOne-LLC/LayerOne-Agents` <a href="#standalone-agents--layerone-llclayerone-agents" id="standalone-agents--layerone-llclayerone-agents"></a>

The monitoring and Looking Glass Python agent, checked out at `../LayerOne Agents`. See [installation and service operations](/monitoring-agent.md).

## Proxmox microVM package — `LayerOne-LLC/pve-microvm-secure` <a href="#proxmox-microvm-package--layerone-llcpve-microvm-secure" id="proxmox-microvm-package--layerone-llcpve-microvm-secure"></a>

The hardened Proxmox microVM package, checked out at `../pve-microvm`. See [the overview](/pve-microvm.md) and [development and operations](/pve-microvm/working-process.md).

## Required documentation access <a href="#required-documentation-access" id="required-documentation-access"></a>

All projects require the connected GitBook MCP before work begins. Stop if it is unavailable, disconnected, unauthenticated, or denied access, and ask the user to restore access. Local Markdown, cached docs, and direct site fetches are not substitutes. After access is confirmed, author documentation changes through GitBook MCP as part of the same feature task.

## How the systems connect <a href="#how-the-systems-connect" id="how-the-systems-connect"></a>

* The platform's **Aegis** surface ([§10](/platform/aegis.md)) consumes Network Monitor telemetry: DDoS incidents, open ports and potential vulnerabilities. The integration contract and its ownership split are documented on that page.
* The **application platform** (`apps/paas/`) reuses the VPS provisioning job engine ([§5.1](/platform/vps/provisioning.md)) but is otherwise isolated from the VPS estate.
* The **node agent** is driven entirely by the platform's web-hosting control plane ([§6.2](/platform/web-hosting/provisioning.md)).

## Do not commit <a href="#do-not-commit" id="do-not-commit"></a>

The code and documentation repositories carry the same rule for AI agents: never run `git commit`, `git push`, `git merge` or `git checkout -b`, and do not `git add` unless asked. Report code diffs and published GitBook changes. Documentation publication through GitBook MCP and its automatic Git Sync are the intended workflow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.layeronecloud.com/ai/repositories.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.