PenterDocumentationGetting started
Documentation

Getting started

Install PENTER on Windows, connect your account and complete your first authorized investigation. Docker and WSL are not required for basic setup; optional integrations have clear beta limits.

Start

A clean first setup, without unnecessary tools

Recommended

New to PENTER?

Download the official Windows build when the beta channel is open, approve your Desktop device, choose a model and create your first scoped workspace. Start with Browser/HTTP tools.
Optional · limited in beta

Using Docker, Kali or MCP?

Complete the basic Desktop setup first. Docker is optional and only offline containers are allowed; packaged-beta native shell, WSL/Kali and MCP execution remain blocked by safety policy.
Public beta rollout status
Windows downloads may still be unavailable while release checks are in progress. If the Download page has no active installer, that is a release gate rather than a setup problem. See current availability.
01

Before you start

  • Use a target or environment you are explicitly authorized to assess.
  • Have access to the PENTER account that should own the desktop device and Cloud usage.
  • You can start without Docker, Kali or MCP. The packaged public beta supports the scoped Browser/HTTP path; unconfined local command execution is restricted.
  • For Browser Agent in a packaged build, allow the first-run Chromium download when prompted.
  • If you plan to use optional offline Docker tools, have Docker Desktop with a working local Linux engine; this is not needed for your first Browser/HTTP investigation.
02

Install PENTER Desktop

Download the current Windows installer from penter.dev/download when the public channel is available. The packaged app is an Electron desktop application; the web dashboard is not a substitute for Desktop when you need scoped local Browser/HTTP tooling. Native shell and MCP processes remain unavailable in packaged public-beta builds.

  1. 1
    Download the current installer
    Use the official Download page after beta downloads are enabled. Check the linked version and SHA-256; do not use unofficial mirrors.
  2. 2
    Install and open PENTER
    Run the Windows x64 installer. The beta build is unsigned, so Windows may show a trust warning; verify the release source and checksum. Do not disable antivirus protection.
  3. 3
    Complete the five-step setup wizard
    The current wizard walks through Welcome → AI → Target → Workspace → Ready, including provider/model selection, engagement name/type, target/domain and an optional local workspace folder.
  4. 4
    Start the guided tour
    After setup, PENTER can introduce the workbench surfaces before you begin the real engagement.
03

Authorize the desktop device

Device authorization ties the Desktop installation to your PENTER account without asking the desktop to retain your website password. Desktop requests a short-lived code and the signed-in website approves that request.

  1. 1
    Request a device code in Desktop
    PENTER creates a temporary authorization request.
  2. 2
    Open the authorization page while signed in
    Approve the code only if it matches the desktop session you are currently setting up.
  3. 3
    Let Desktop finish the exchange
    After approval, the desktop receives its PENTER access credential and appears in Dashboard → Devices.
  4. 4
    Revoke lost or old devices
    Use the Devices page when a machine should no longer be trusted.
Device credentials are revocable
Treat a desktop authorization like any other long-lived client credential. Removing a device from the account is the correct response when the machine is retired, lost or no longer under your control.
04

Create one workspace per engagement boundary

A workspace should represent one coherent authorized investigation. Keeping unrelated targets in separate workspaces makes target context, evidence, MCP configuration, browser state and agent reasoning easier to audit.

  • Set the intended target or target family before asking for active checks.
  • Keep the engagement authorization boundary narrower than the technical network boundary whenever possible.
  • Use a new workspace when moving to a different customer, contract, environment or unrelated target set.
  • Store engagement notes and PoCs alongside the workspace rather than mixing them into global state.
05

Run the first agent workflow

Start with a bounded objective. The agent works best when it knows the target context, what outcome you want, and whether it should inspect, plan, execute, verify or document.

Example operator request
Map the public application surface for this authorized target. Start with passive/basic checks, show each active command before execution, and separate observations from verified findings.

The expected flow is reasoning → tool proposal → execution/approval → result → updated reasoning. PENTER should not invent output for a command that has not run.

06

Choose Local or Cloud execution deliberately

Local execution

For authorized targets, use the scoped Browser, HTTP and Request Lab tools. In the packaged public beta, native shell, WSL/Kali commands and MCP execution are blocked; managed Docker is offline-only.

Cloud execution

Cloud AI chat is separate from the Cloud command runner. Command execution is currently disabled server-side for the public beta, even if a command would otherwise meet the target policy.

Cloud CLI is not a beta execution fallback
Cloud command execution remains off until its release gates pass. For private labs, use scoped local Desktop tools within your authorization; do not attempt to bypass packaged execution restrictions.
07

Optional: connect Docker Desktop

Docker is not required for login, AI chat or Browser/HTTP investigations. Use it only when you need an approved, locally available image for offline tool execution. Networked containers are intentionally disabled in the packaged public beta.

  1. 1
    Install and start Docker Desktop
    Use Docker Desktop with the WSL 2 Linux-container backend. Wait until the app says its engine is running.
  2. 2
    Confirm the Linux Engine is reachable
    On Windows, desktop-linux is the typical active context. A missing named pipe usually means the engine has not started yet, even if the CLI is installed.
  3. 3
    Pull a trusted image explicitly
    For a basic connectivity check, alpine:3.21 is a lightweight example. PENTER does not permit surprise image pulls while executing tools.
  4. 4
    Check PENTER Settings → Docker
    Refresh the engine status, select an approved local image and keep network=none. A stopped Docker Desktop Windows service alone does not imply the WSL2 engine is unhealthy.
Windows CMD · engine diagnostics
docker context ls
docker context use desktop-linux
docker info --format "{{.OSType}}"
wsl --status
wsl -l -v
Windows CMD · optional image
docker pull alpine:3.21
docker image ls
Never enable bridge networking to get past a block
PENTER's packaged runner enforces network=none. A Docker bridge is not a per-target scope firewall. If a task requires outbound network requests, use an approved scoped Browser/HTTP workflow instead.

Docker pipe missing, WSL setup confusion or image not found? Find the matching fix.

08

Updates in the restricted public beta

Packaged Windows builds can check the configured update feed, but the beta deliberately does not auto-download or auto-install updates. The update feed can also be unavailable while the public release channel is gated.

  • Use the official Download page to obtain a newly approved release when available.
  • Compare the installer version and published SHA-256 checksum to the release metadata.
  • Do not turn off Windows protections or install from unofficial mirrors just to resolve an update warning.
  • Prerelease updates and silent install-on-quit are not enabled in the current beta.
09

Need help with a specific error?

The troubleshooting guide has searchable fixes for device codes, provider errors, failed Chromium downloads, Docker's Windows named pipe and public-beta restrictions. The guides are for PENTER Desktop users rather than developers building the application from source.

Open setup troubleshooter →
Before sharing error logs
Remove access tokens, API keys, browser cookies, customer data and private target details. An error code and PENTER/Windows version are usually a safer first diagnostic.
Next step

Ready to get started?

Follow the setup guide, install the current approved Desktop release, and connect your account.