Installation

NAT can be installed via pip (Python package), Docker, or used directly in GitHub Actions without a local install.

System requirements

Requirement	Minimum	Recommended
Python	3.10	3.11+
RAM	512 MB	2 GB
Disk	200 MB	1 GB
OS	Linux, macOS, Windows (WSL2)	Linux or macOS

Install via pip

pip install nat-engine installs the full NAT engine including the CLI, local report generation, and self-hosted server mode.

pip install nat-engine

Verify the installation

nat --version
# nat-engine 1.x.x

Upgrade to the latest version

The recommended way to upgrade is via pip:

pip install --upgrade nat-engine

The built-in upgrade command offers additional options:

nat upgrade          # upgrade and apply migrations
nat upgrade --check  # check for updates without installing
nat upgrade --migrate  # upgrade and apply database schema changes (self-hosted)

See the Upgrade & Uninstall guide for all options.

Install a specific version

pip install nat-engine==1.2.0

Install in a virtual environment (recommended)

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows
pip install nat-engine

Install via Docker

docker pull natengine/nat:latest
docker run --rm natengine/nat:latest nat --version

See the Docker Deployment guide for production Docker setup.

Install via GitHub Actions

No local installation needed — use the official nat-action in your workflow:

- uses: nat-testing/nat-action@v1
  with:
    api-url: https://api.example.com
    api-key: ${{ secrets.NAT_API_KEY }}

See the CI/CD Integration guide for the full workflow reference.

Self-hosted server mode

After installing via pip, you can run NAT as a local server that exposes a REST API and dashboard:

Start the server

nat server start --port 8080

Open the dashboard

Navigate to http://localhost:8080 in your browser.

Configure via environment variables

Variable	Description	Default
`NAT_PORT`	Server listen port	`8080`
`NAT_HOST`	Bind address	`127.0.0.1`
`NAT_DATA_DIR`	Directory for scan data and reports	`~/.nat/data`
`NAT_LOG_LEVEL`	Log verbosity (`debug`, `info`, `warn`, `error`)	`info`
`NAT_SECRET_KEY`	Secret used to sign session tokens	Auto-generated

See the Self-Hosted Setup guide for a complete production deployment walkthrough.

Database setup (server mode)

When running NAT in server mode for persistent SaaS or multi-tenant deployments, you must configure a PostgreSQL database and apply the schema migrations before starting the server.

⚠️

Without DATABASE_URL, NAT stores all scan data in memory. All scan data is lost on restart. Set DATABASE_URL before starting the server in any persistent deployment.

Set the database URL

export DATABASE_URL=postgresql://user:password@localhost:5432/nat

Apply Alembic migrations

Run the database migrations to create (or upgrade) the schema. Run this from the root of the NAT repository where alembic.ini is located (Alembic is included with nat-engine):

alembic upgrade head

This must be run once on first install and again after each NAT upgrade that includes schema changes.

Start the server

nat server start --port 8080

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/nat`

For a complete production database setup, see the Self-Hosted Setup guide.

Uninstall

To uninstall the Python package:

pip uninstall nat-engine

The built-in uninstall command provides a more thorough clean-up:

nat uninstall          # removes config files, data, and shell completions, then the package
nat uninstall --purge  # also removes database tables and Docker volumes

See the Upgrade & Uninstall guide for all options.

Next steps

Quickstart — scan your first API in five minutes
Your First Scan — detailed first scan walkthrough
Worker Pools — parallel distributed test execution with nat worker launch
Exporter Configuration — set up any of the 11 built-in exporters including Sentry and Bugzilla
Self-Hosted Setup — production self-hosted deployment

Was this helpful?

Pipeline Quickstart Your First Scan