Global Usage

Install AllySec Forge system-wide and run it from any directory on any target.

System-Wide Install

Bun installs the package globally:

bun install -g allysec

This places the allysec binary in Bun's global bin directory. Verify it is on your PATH:

which allysec
allysec --version

If allysec is not found, add Bun's bin directory to your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.bun/bin:$PATH"

Running From Any Directory

The CLI is directory-agnostic. You do not need to be in the project root.

cd /tmp
allysec --target example.com

Engagement output defaults to ./outputs/<engagement-name>/ relative to the directory where allysec is invoked. To centralize output:

allysec --target example.com --output-dir /opt/allysec/engagements/

Container Management

The Kali container is Docker-managed. It auto-deploys on first run and persists across sessions.

# Check container status
docker ps --filter name=allysec-kali

# View container logs
docker logs allysec-kali

# Stop the container
docker stop allysec-kali

# Remove and re-deploy
docker rm allysec-kali
allysec --target example.com  # auto-deploys fresh

The image is ghcr.io/allyseclabs/allysec-kali-full:latest. Docker pulls it once and caches locally. Container restart reuses the existing image unless you explicitly pull.

Updating

Update the CLI globally:

bun install -g allysec@latest

Update the Kali container image:

docker pull ghcr.io/allyseclabs/allysec-kali-full:latest
docker rm -f allysec-kali
# Next allysec run auto-deploys the new image

Check your current versions:

allysec --version
docker inspect allysec-kali --format '{{.Image}}'

Config Location

The .env file is read from the directory where allysec is invoked, or you can set a custom path:

allysec --target example.com --env /etc/allysec/.env

For system-wide configuration, place .env in /etc/allysec/.env and use the --env flag or set ALLY_SEC_ENV_PATH.

---

Quick Start -- Environment Variables