PenterDocumentationFind your fix.
Support / Troubleshooting

Find your fix.

A practical troubleshooting guide for PENTER Desktop. Search by the exact error message, choose the feature that isn't working and follow safe, step-by-step fixes.

01 · Help library

Search common issues

14 solutions
Installation

The Windows download button is unavailable

The public-beta release channel has not yet been enabled on the website.

Steps to fix

  1. 01Check the official Download page for the current release status.
  2. 02When downloads are enabled, use the release linked there and verify its published SHA-256 if provided.
  3. 03Do not download private source-repository builds or installer files from unofficial mirrors.
Check download availability
Installation

Windows displays a publisher or SmartScreen warning

The beta installer is unsigned; a Windows trust warning is possible even with an intact download.

Steps to fix

  1. 01Confirm you downloaded the installer from the official PENTER Download page and its linked public release.
  2. 02Compare the SHA-256 with the checksum on the release page before deciding whether to continue.
  3. 03If Windows Security identifies an actual threat, stop and report it. Do not disable Defender or add broad antivirus exclusions.
Official installer and checksum
Installation

PENTER does not open, or closes immediately

A first launch exits or the Desktop window never appears.

Steps to fix

  1. 01Check that this is the Windows x64 installer rather than a source-code archive.
  2. 02Restart Windows and retry once after closing any existing PENTER process.
  3. 03Check the Windows Security protection history for a specific blocked executable rather than disabling protections.
  4. 04If it still fails, record the version, Windows build, exact error, and whether the window ever opened.
Go to first-time setup
Account

Device code expired or approval does not complete

The Desktop authorization code has timed out, or the website and Desktop are using different accounts.

Steps to fix

  1. 01Request a new device code in Desktop and use the current code only.
  2. 02Sign in to penter.dev with the account that should own this PC.
  3. 03Check the code shown by Desktop before approving the request on the website.
  4. 04If the device was revoked, start a new authorization instead of reusing the old token.
Manage authorized devices
Account

Login or MFA is failing

A login, multi-factor step, or device security challenge fails.

Steps to fix

  1. 01Confirm that you are using the correct account and a current authenticator code when MFA is enabled.
  2. 02Check the device clock and retry a fresh sign-in rather than repeatedly reusing an expired challenge.
  3. 03Use the password-reset flow if you cannot sign in. Never send passwords, recovery codes, session tokens or API keys with a support report.
Reset your password
Agent & AI

The model returns an error or is unavailable

Cloud provider errors, insufficient credits, rate limits, or an offline local model.

Steps to fix

  1. 01Check whether the failure affects one selected model or all models.
  2. 02For Cloud AI, verify your PENTER account/device authorization and available usage in the dashboard.
  3. 03For an Ollama/local provider, confirm the model and server work independently on this machine.
  4. 04Record the exact error or request ID (without credentials) instead of repeatedly submitting the same request.
Agents and model configuration
Agent & AI

The agent stops after one action or has no tool results

The conversation returns a conclusion without the expected investigation evidence.

Steps to fix

  1. 01Check the execution timeline for a real tool request and result. A model description is not proof a command ran.
  2. 02Confirm that the engagement scope and the chosen Browser/HTTP capability are available.
  3. 03Ask for a bounded multi-step investigation that verifies findings and explicitly reports blocked steps.
  4. 04If an execution surface is blocked by beta policy, do not attempt to bypass it through another tool.
Understand agent execution
Browser

Browser Agent cannot start on first use

Managed Chromium is missing or its first-use download failed.

Steps to fix

  1. 01Allow the prompted, first-run managed Chromium download.
  2. 02Verify that your network can reach the Playwright browser-download CDN.
  3. 03Retry from inside Desktop and check the explicit error if it still fails.
  4. 04Do not copy a browser executable from an untrusted website into PENTER.
Browser Agent setup
Browser

Navigation is blocked or page actions stop working

The browser rejects a different target, or a selector becomes stale after navigation.

Steps to fix

  1. 01Confirm that the current workspace is bound to the intended authorized target.
  2. 02Start a new engagement when changing to a different customer or scope.
  3. 03Refresh the page snapshot/elements after navigation and select the new element.
  4. 04Redirects, popups and WebSocket connections may be restricted in the beta; do not treat a blocked out-of-scope URL as a broken browser.
Workspace and scope boundaries
Docker

Docker pipe not found / cannot connect to Docker Engine

open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.

Steps to fix

  1. 01Open Docker Desktop and confirm its Linux engine reports Running.
  2. 02Check the active context. On a normal Docker Desktop/WSL2 setup it should be desktop-linux.
  3. 03Test the engine with docker info and expect linux before retrying PENTER.
  4. 04If the pipe remains missing, check Docker Desktop status and the WSL 2 backend before restarting Docker Desktop.
  5. 05A stopped com.docker.service is not by itself proof of failure when the WSL 2 backend and Linux engine are working.
Windows CMD · Docker Desktop
docker context ls
docker context use desktop-linux
docker info --format "{{.OSType}}"
wsl --status
wsl -l -v
Docker optional setup
Docker

A Docker image is missing or cannot be used

PENTER cannot find the approved image on the selected local Docker Engine.

Steps to fix

  1. 01Ensure Docker Desktop is running in Linux-container mode.
  2. 02Download only an image you trust, using PENTER Settings → Docker or the Docker CLI.
  3. 03Select the image in PENTER and keep networking set to none for the packaged beta.
  4. 04An offline managed container cannot access the internet to install tools while it runs.
Windows CMD · optional
docker info --format "{{.OSType}}"
docker pull alpine:3.21
docker image ls
Set up Docker safely
Beta limits

WSL/Kali, native shell, MCP or networked Docker is blocked

Unconfined execution is intentionally disabled in the packaged public beta.

Steps to fix

  1. 01This is a security limitation, not an installation failure. Native shell, WSL/Kali commands and MCP process/tool execution are blocked in packaged builds.
  2. 02Docker execution is available only with network=none. Docker Compose up and remote Desktop Relay execution are also disabled.
  3. 03For target-facing investigations, use the approved scoped Browser, HTTP and Request Lab surfaces.
  4. 04Do not disable protection or switch to a development build to bypass an authorization boundary.
Beta security restrictions
Beta limits

Cloud command execution or checkout returns unavailable

CLOUD_EXECUTION_UNAVAILABLE, HTTP 503, or checkout disabled during the beta.

Steps to fix

  1. 01Cloud command execution and paid checkout remain server-side disabled until their release gates pass.
  2. 02Cloud AI chat is a separate capability; check its account/model error independently.
  3. 03Use the supported scoped local Desktop tools for authorized testing; do not treat a 503 gate as a configuration problem on your PC.
Cloud execution availability
Installation

Automatic updates are not installing

The beta only checks for updates; silent download and auto-install are disabled.

Steps to fix

  1. 01The packaged Windows application can check the configured release feed, but beta builds do not auto-download or auto-install.
  2. 02The update feed may return unavailable until the beta channel is enabled.
  3. 03When a verified new release is published, use the official Download page and compare its version and SHA-256.
Find the latest approved build

Still stuck? Note your PENTER and Windows versions and exact error. Remove API keys, tokens, browser cookies and customer data before sharing logs.

02 · Quick checks

Check the basics first

Do I need Docker, Kali or WSL to use PENTER?
No. Docker is optional for offline managed containers. You can connect your account and use supported scoped Browser, HTTP and Request Lab features without it. The packaged beta deliberately blocks native shell, WSL/Kali and MCP execution.
Docker Desktop is installed, but PENTER cannot connect.
The Docker CLI can be installed even when the Linux engine is stopped. Open Docker Desktop, verify the engine is running and use the Docker-specific fix above. A stopped Windows Docker service alone does not prove the WSL 2 engine is broken.
Why can't I use some tools in the public beta?
Features that could contact unauthorized network destinations are deliberately restricted until their scope enforcement is verified. See the security guide for the supported boundaries; do not attempt to bypass them.
Will PENTER update itself?
The current packaged beta may check for updates, but it does not download or install them automatically. Check the official download page for an approved newer build.
03 · Login & access

Account and device problems

My device authorization code expired.
Generate a new code in PENTER Desktop and approve it on the website while signed into the correct account. Never reuse an expired code or approve one you did not request.
Cloud AI is unavailable, but the Desktop app opens.
Confirm your account/device connection and current model selection. Check usage in your dashboard and keep the request ID if the provider returns an error. Browser and local features have separate availability.
I lost access to an old device.
Open Dashboard → Devices and revoke the old installation. Reauthorize your current device using a new code.
04 · Support

What to share if the issue remains

Note your PENTER Desktop version, Windows version, the feature you were using and the exact error text. Explain which steps you already tried. That gives support useful context without collecting your engagement data.

Remove private information before sharing logs
Never send passwords, MFA codes, API keys, device tokens, cookies, customer evidence, or private target addresses with a report. Start with the error code and software versions.

New to PENTER? Follow the setup guide from the beginning.

Next step

Ready to get started?

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