> For the complete documentation index, see [llms.txt](https://docs.safetycli.com/safety-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.safetycli.com/safety-docs/firewall/installation-and-configuration.md).
# Installation and Configuration
## System Requirements
Before installing Safety Firewall, ensure your system meets the following requirements:
* **Operating Systems**:
* macOS 10.14 or later
* Linux (Ubuntu, Debian, CentOS, RHEL)
* Windows 10 or later
* **Python**: Version 3.8 or later
{% hint style="warning" %}
Safety Firewall works with pip, uv, poetry, and npm. We'll automatically detect and configure the package managers on your system.
{% endhint %}
## Before You Begin
### Create a Safety Account
If you don't already have a Safety account, [sign up here](https://platform.safetycli.com/register).
### Get Your Organization Ready
To use Safety Firewall, your organization must have the Firewall feature enabled. If you're unsure whether your organization has access, contact your Safety administrator or [reach out to our support team](mailto:support@safetycli.com).
{% hint style="info" %}
If your Safety account was created before March 2025, the Firewall feature is disabled by default to ensure no breaking changes occur. To enable Firewall, please reach out to our [support team](mailto:support@safetycli.com).
{% endhint %}
## 1. Installation
### 1.1 Install Safety CLI
Open your terminal and run the following command:
{% tabs %}
{% tab title="pip" %}
```bash
pip install safety
```
{% hint style="info" %}
If you already have Safety installed, please use `pip install -U safety` . The minimum version required to run Safety Firewall is v3.5.0.
{% endhint %}
{% endtab %}
{% tab title="UV" %}
```bash
uv tool install safety
```
{% endtab %}
{% endtabs %}
### 1.2 Authenticate with Safety
Run the authentication command:
```bash
safety auth login
```
This will open a browser window where you can log in to your Safety account. Once authenticated, your terminal will show a success message.
### 1.3 Verify Authentication Status
You can check your authentication status at any time with:
```bash
safety auth status
```
This should display your email address and confirm that you're authenticated.
{% hint style="warning" %}
Make sure you're authenticated before proceeding to the next step. If you're not authenticated or don't have the Firewall feature enabled, the `safety init` command will not be available.
{% endhint %}
## 2. Initialization of Safety Firewall
After installing the Safety CLI and authenticating your account, you can initialize Safety Firewall with a single command:
```bash
safety init
```
This command starts the interactive setup process for Safety Firewall.
#### What Happens During Initialization
When you run `safety init`, the following actions take place:
1. Safety checks if you're authenticated and asks if you want to setup Safety Firewall.
2. Safety identifies the package managers on your system (pip, poetry, etc.)
3. Safety configures secure aliases for each package manager
4. Safety detects if there is a codebase in your current directory
5. Safety offers to set up this codebase for ongoing protection
{% hint style="warning" %}
**IMPORTANT**: After initialization, you'll need to refresh your shell environment for the aliases to take effect. This is typically done by running `source ~/.safety/.safety_profile` or the equivalent for your shell.
{% endhint %}
## 3. Verifying Firewall Installation
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
{% tabs %}
{% tab title="Mac/Linux" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
which pip
```
You should see output similar to:
```
pip: aliased to safety pip
```
If you don't see this output, your shell environment may need to be reloaded.
{% endtab %}
{% tab title="CMD.exe" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
where pip
```
You should see output similar to:
```
pip: aliased to safety pip
```
If you don't see this output, your shell environment may need to be reloaded.
{% endtab %}
{% tab title="PowerShell" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
gcm pip
```
You should see output similar to:
```
pip: aliased to safety pip
```
If you don't see this output, your shell environment may need to be reloaded.
{% endtab %}
{% endtabs %}
## Understanding Safety Firewall Configuration
### How Safety Firewall Intercepts Commands
Safety Firewall intercepts your package manager commands so it can check a package before it installs. The mechanism differs by operating system.
On macOS and Linux, Safety writes shell aliases into `~/.safety/.safety_profile` and sources that file from your shell startup files. Running `pip install requests` matches the `pip` alias, which routes the command through Safety Firewall.
On Windows, Safety writes `.bat` shims into `%USERPROFILE%\AppData\Local\safety\`, adds that directory to your `PATH`, registers a Command Prompt macro, and adds functions to your PowerShell profile.
Once a command is intercepted, Safety Firewall:
1. Analyzes the requested package(s) for vulnerabilities and malicious code
2. Applies your organization's security policies
3. Either warns, blocks, or allows the installation
4. Records the installation event in the Safety Platform
### Where Command Interception Does Not Reach
Interception applies to the command you type, so three cases fall outside it.
1. An alias matches only the first word of a command. `python -m pip install requests` runs pip without matching the `pip` alias.
2. A script or tool that starts pip as a subprocess does not inherit the aliases from your interactive shell.
3. A container image build has no shell startup files, so no aliases exist. Write `safety pip install` explicitly in a `RUN` line to keep those installs covered.
Safety Firewall also points your package managers at the Safety index, which is a separate mechanism from interception. That configuration is persistent and applies to any command the package manager runs, whether or not it was intercepted.
### How Each Package Manager Is Configured
The Safety index proxies the public PyPI and npm registries. `safety init` points each package manager at it.
| Package manager | System-wide | Per project |
| --------------- | ------------------------------------- | ------------------------------------------------- |
| pip | `index-url` in your user `pip.conf` | `-i ` line added to requirements files |
| uv | An index entry in your user `uv.toml` | An index entry in `pyproject.toml` |
| npm | `registry` in your global `.npmrc` | `registry` in the project `.npmrc` |
| poetry | Not configured | A `safety` source added to `pyproject.toml` |
Poetry is the exception. Safety configures Poetry per project, so a Poetry project that Safety has not configured resolves from PyPI directly. Running a Poetry command through `safety poetry` adds the source to that project before the command runs.
### What Can Override Your Configuration
Package managers read configuration from more than one location, and the setting closest to the command wins. Four things override what `safety init` writes.
1. A command-line flag. `pip install --index-url requests` replaces the configured index for that command.
2. An environment variable such as `PIP_INDEX_URL`, which overrides your user configuration file.
3. A configuration file closer to the project. A `pip.conf` inside an active virtual environment overrides your user `pip.conf`.
4. A managed platform that sets an index for you. Hosted notebook and cluster platforms configure a package index at the workspace or cluster level, above anything a startup script writes.
How each package manager handles more than one index decides what the first three mean for you.
**pip** treats every configured index as equal. It queries all of them and installs the highest version it finds, with no preference between them. Adding a second index with `--extra-index-url` therefore does not leave the Safety index in charge. pip's own documentation describes the risk.
> Using the `--extra-index-url` option to search for packages which are not in the main repository (for example, private packages) is unsafe. This is a class of security issue known as dependency confusion.
Replacing the index with `--index-url` does not carry this risk, because pip then queries one index only.
**uv** stops at the first index that carries a package name, so an added index does not compete for names the Safety index already serves.
**poetry** searches all primary sources for every package. Adding your own primary source alongside Safety's means both are searched.
**npm** resolves each package from one registry, chosen by the package's scope, and has no equivalent of `--extra-index-url`. Lock files are the case to watch. A `package-lock.json` created while a different custom registry was configured records that registry, and `npm ci` keeps installing from it after you configure the Safety registry.
### Checking Your Configuration
To see which index pip uses and which file set it, run:
```bash
pip config debug
```
The output lists every configuration file pip checked, in precedence order, with the values each one sets. `pip config list` shows the effective values without showing their source.
For npm, run:
```bash
npm config get registry
npm config list
```
`npm config list` labels each value with the file or environment variable it came from.
For uv and Poetry, check the index entries in `uv.toml` or `pyproject.toml` directly.
Installs run through Safety Firewall set the index for that command only, so these commands show your configuration rather than the index a Safety-intercepted install used.
### Configuration Files
Safety Firewall creates several configuration files on your system:
* **`~/.safety/`**: The main directory for Safety Firewall configuration
* **`~/.safety/config.toml`**: Global configuration file
* **`.safety-project.ini`**: Project-specific configuration (created in each code base directory)
{% hint style="info" %}
Most users won't need to manually edit these files. Configuration changes are typically made through the Safety CLI or Safety Platform
{% endhint %}
## Configuring Your First Codebase
During initialization, Safety may detect a requirements file or Python project in your current directory and offer to configure it as a code base. If you accept, Safety will:
1. Create a `.safety-project.ini` file in the directory
2. Perform an initial scan of the project's dependencies
3. Upload the scan results to the Safety Platform
4. Configure the directory for ongoing monitoring
### Manual Codebase Configuration
If you want to set up a codebase after initialization, navigate to the project directory and run:
```bash
safety codebase init
```
Follow the prompts to name the code base and set up initial scanning.
{% hint style="info" %}
A "codebase" in Safety refers to a project that is tracked and monitored by the Safety Platform. When a codebase is configured, any package installations or removals within that directory will automatically trigger scans and update the project's security status in the Safety Platform.
{% endhint %}
### Configuration Options
#### Supported Package Managers
Safety Firewall currently supports the following package managers:
* **pip**: Supported system-wide and per project
* **uv**: Supported system-wide and per project
* **npm**: Supported system-wide and per project
* **poetry**: Supported per project
Safety configures Poetry by adding a source to a project's `pyproject.toml`, so a Poetry project that Safety has not configured resolves from PyPI directly. See [How Each Package Manager Is Configured](#how-each-package-manager-is-configured).
Additional package managers will be added in future updates.
---
# 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.safetycli.com/safety-docs/firewall/installation-and-configuration.md?ask=&goal=
```
`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.
