AGENTS.md · netbox-community/netbox

Sections

1. Repository Overview
2. Tech Stack
3. Repository Map
4. Architecture
5. Commands
6. Development Setup
7. Testing
8. CI/CD
9. Common Tasks
10. Conventions and Patterns
11. AI Policy
12. Branch & PR Conventions
13. PR Submission Requirements
14. Troubleshooting
15. Gotchas
16. References

First lines (shown under the repo's Apache-2.0 license)

# NetBox

## Repository Overview

NetBox is an extensible open-source network source-of-truth application powering network automation. It manages network infrastructure data including data center infrastructure (DCIM), IP address management (IPAM), circuits, virtualization, wireless, VPNs, and more. It supports a plugin ecosystem and exposes both a REST API and GraphQL API.

NetBox is the core product maintained by NetBox Labs. The current version is 4.6 (Python 3.12+, Django 6.x).

## Tech Stack

- Python 3.12+ / Django 6.x / Django REST Framework 3.x
- PostgreSQL (required), Redis (required for caching/queuing)
- GraphQL via Strawberry, background jobs via django-rq
- django-tables2 for list views, django-filter for filtering
- drf-spectacular for OpenAPI/Swagger schema generation
- Docs: MkDocs with mkdocs-material theme (in `docs/`)
- Ruff for lint (config in `pyproject.toml`)

## Repository Map

```text
.
├── netbox/                    — Django project root (run manage.py from here)
│   ├── manage.py
│   ├── netbox/                — Core settings, URLs, WSGI, plugin infrastructure
│   │   ├── settings.py        — Main Django settings
│   │   ├── configuration.py   — Instance configuration (gitignored)
│   │   ├── configuration_example.py — Configuration template
│   │   ├── configuration_testing.py — Test configuration
│   │   ├── urls.py            — Root URL routing
│   │   ├── wsgi.py            — WSGI entrypoint
│   │   ├── api/               — Core REST API infrastructure
│   │   ├── graphql/           — Core GraphQL schema
│   │   ├── models/            — Core model infrastructure (features, mixins)
│   │   ├── navigation/        — Navigation menu system
│   │   ├── plugins/           — Plugin system infrastructure
│   │   ├── registry.py        — Object registry
│   │   ├── search/            — Full-text search implementation
│   │   ├── ui/                — UI utilities
│   │   └── tests/             — Core framework tests
│   ├── account/               — User account management
│   ├── circuits/              — Circuit and provider management
│   ├── core/                  — Core data management (data sources, jobs)
│   ├── dcim/                  — Data center infrastructure (devices, racks, cables, etc.)
│   ├── extras/                — Cross-cutting features (custom fields, tags, webhooks, scripts)
│   ├── ipam/                  — IP address management (prefixes, addresses, VLANs, etc.)
│   ├── tenancy/               — Tenancy and organization
│   ├── users/                 — User management and tokens
│   ├── utilities/             — Shared utilities (no models)
│   ├── virtualization/        — Virtual machines and clusters
│   ├── vpn/                   — VPN tunnels and configurations
│   ├── wireless/              — Wireless LANs and links
│   ├── templates/             — Django templates (per-app subdirectories)
│   ├── static/                — Compiled static assets
│   ├── project-static/        — Source static assets
│   ├── media/                 — User-uploaded media
│   └── translations/          — i18n translation files
├── docs/                      — MkDocs documentation source
│   ├── administration/
│   ├── configuration/
│   ├── customization/
│   ├── development/           — Contributing guide, code style
│   ├── features/
│   ├── getting-started/
│   ├── installation/
│   ├── integrations/
│   ├── models/                — Per-model documentation (by app)
│   ├── plugins/
│   ├── reference/
│   └── release-notes/
├── scripts/                   — Database management and verification scripts
├── contrib/                   — Example configs (systemd, nginx, generated schemas)
├── pyproject.toml             — Project metadata, ruff config
├── requirements.txt           — Python dependencies
└── mkdocs.yml                 — Docs site configuration
```

## Architecture

### App Structure

Each Django app (account, circuits, core, dcim, extras, ipam, tenancy, users, virtualization, vpn, wireless) follows a standard layout:

```text
<app>/
├── __init__.py
├── models/          — Database models (or models.py for smaller apps)
├── migrations/      — Database migrations
├── api/
│   ├── serializers.py
│   ├── views.py     — DRF viewsets
│   └── urls.py      — NetBoxRouter registrations
├── forms/           — Django forms (model forms, filter forms, bulk edit, etc.)
├── tables/          — django-tables2 table definitions
├── graphql/
│   └── types.py     — Strawberry GraphQL types
├── filtersets.py    — django-filter FilterSets
├── choices.py       — ChoiceSet subclasses
├── views.py         — UI views (registered with register_model_view())
├── urls.py          — URL routing
├── search.py        — SearchIndex registrations
├── signals.py       — Django signal definitions (where applicable)
└── tests/
    ├── test_api.py
    ├── test_filtersets.py
    ├── test_models.py
    ├── test_views.py
    └── test_forms.py
```

### Views

Use `register_model_view()` to register model views by action (e.g. "add", "list", etc.). List views typically don't need to add `select_related()` or `prefetch_related()` on their querysets — prefetching is handled dynamically by the table class so that only relevant fields are prefetched.

### REST API

DRF serializers live in `<app>/api/serializers.py`; viewsets in `<app>/api/views.py`; URLs auto-registered in `<app>/api/urls.py`. `NetBoxModelSerializer` provides standard fields including `url`, `display`, `tags`, and `custom_fields`. drf-spectacular generates the OpenAPI schema automatically. REST API views typically don't need to add `select_related()` or `prefetch_related()` — prefetching is handled dynamically by the serializer.

### GraphQL

Strawberry types live in `<app>/graphql/types.py`. The core GraphQL schema is assembled in `netbox/netbox/graphql/`. Use Strawberry's `@strawberry.type` and `auto` field resolution, following the patterns in existing apps.

### Background Jobs

django-rq drives background task processing. Job classes live in `core/jobs.py` and app-specific `jobs.py` files. Use `JobRunner` subclasses (from `netbox.jobs`) for all background work. The `core` app exposes job status in the UI.

### Plugin System

Plugin infrastructure lives in `netbox/netbox/plugins/`. Plugins are Django apps registered in `PLUGINS` (configuration.py). The plugin API exposes stable extension points: custom models, views, navigation, template extensions, search indexes, object actions, and event rules. Internal NetBox APIs are subject to change without notice.

### Filtering

FilterSets live in `<app>/filtersets.py`, using `NetBoxModelFilterSet` as the base. Used for both UI filtering and API `?field=` params. FK filters must declare an explicit `<field>_id = ModelMultipleChoiceFilter(field_name='<field>', ...)` — don't rely on `Meta.fields` to auto-generate `_id` variants.

### Extras App

`extras` is a catch-all for cross-cutting features: custom fields, custom links, tags, webhooks/event rules, export templates, config contexts, saved filters, bookmarks, notifications, scripts, and reports. New cross-cutting features belong here. Use `FeatureQuery` for generic relations (config contexts, custom fields, tags, etc.).

## Commands

All commands run from the `netbox/` subdirectory with the venv active. There is no Makefile or Justfile; use raw commands.

| Command | What it does |
|---|---|
| `python manage.py runserver` | Start development server |
| `python manage.py test` | Run full test suite (set `NETBOX_CONFIGURATION` first — see Testing) |
| `python manage.py test --keepdb --parallel 4` | Faster test run (no DB rebuild, parallel) |
| `python manage.py test dcim.tests.test_api` | Run a single test module |
| `python manage.py makemigrations` | Generate migrations after model changes |
| `python manage.py migrate` | Apply migrations |
| `python manage.py nbshell` | NetBox-enhanced interactive shell |
| `python manage.py collectstatic` | Collect static assets |
| `ruff check` | Lint (run from repo root) |
| `mkdocs serve` | Preview documentation |
| `mkdocs build` | Build static docs site |

## Development Setup

```bash
python -m venv ~/.venv/netbox