home  /  docs  /  getting started

Getting started.

For someone who just signed up at pentestai.xyz and wants to run their first real engagement in the next 15 minutes. If you're trying out the OSS CLI without a workspace, jump to Just the CLI.

What you bought, in 60 seconds

A pentest-ai workspace gives you three things:

  1. The dashboard at app.pentestai.xyz. Multi-user. Shared engagements, shared findings, shared reports. SAML SSO, audit log, IP allowlist, the compliance bits you'd expect.
  2. The CLI, free, open source, MIT-licensed. The same engagements your teammates run from the dashboard, you can run from your terminal. Findings sync if you link the CLI to your workspace.
  3. An MCP server. Expose the same tool surface to Claude Code, Cursor, Claude Desktop, or any MCP-compatible client. Same code path, same results.

You bring your own LLM key (Anthropic, OpenAI, Ollama, or 300+ via LiteLLM). We don't proxy or cache it. The CLI is pure OSS and runs on your machine.

After payment, in order

1. Check your email

Within 60 seconds of Stripe redirecting you to "You're in", you should have an email from [email protected]. Subject line includes "Welcome to pentest-ai".

The email has:

If the email isn't there, check spam. Wait 2 minutes (Stripe's webhook is fast but not instant). If still nothing, email [email protected] with your Stripe receipt ID. We'll resend it in under 30 minutes during business hours.

2. Set your password

Click the link, set the password, log in. If your team is paying for SSO, skip this and go straight to SSO setup at app.pentestai.xyz/settings/sso.

Strong-password rules: minimum 12 chars, no HIBP-pwned passwords. We do not allow weak ones, including for trial users.

3. Run your first engagement

  1. Click + New engagement in the top right.
  2. Enter a target. Use one you have explicit authorization to test. If you don't have one yet, use http://testphp.vulnweb.com (Acunetix-hosted, intentionally vulnerable, public).
  3. Confirm the consent gate. We make you tick a checkbox saying you have authorization. Save the receipt.
  4. Pick a scope: recon (light), full (all phases), or one of the specialty scopes (web, ad, cloud).
  5. Click Start scan. The first findings appear within 30 seconds.

The dashboard streams findings as the agents discover them. You can leave the page; the scan keeps running. When it finishes you'll get an in-app notification.

4. Read the report

Open the engagement, click Report. Three formats:

Reports include the chain analysis (low-sev findings escalated to critical via multi-hop chains), the safe PoCs that confirmed each finding, and a detection-rule section your blue team can drop into Sigma/SPL/KQL.

5. Connect the CLI to your workspace (optional)

The CLI works standalone. If you want findings to sync to the workspace so the dashboard sees them too:

pip install ptai
ptai auth login <YOUR_API_KEY>
ptai start http://testphp.vulnweb.com

Findings from the CLI run land in the dashboard under the same engagement. You can hand off the engagement between CLI and dashboard freely.

To get your API key: dashboard → Settings → API Keys → Generate.

6. Connect your LLM

The CLI runs in deterministic mode without an LLM. To unlock the agent-driven, autonomous mode (recommended), set one of:

export ANTHROPIC_API_KEY=sk-ant-...    # recommended
# or
export OPENAI_API_KEY=sk-...
# or fully local, no cloud:
export PTAI_LLM_PROVIDER=ollama
ollama pull llama3.1
# or any of 300+ via LiteLLM:
export PTAI_LLM_PROVIDER=litellm
export LITELLM_MODEL=openrouter/...

Your key never leaves your machine. The dashboard does not proxy LLM traffic.

Inviting your team

Dashboard → Team → Invite member. They get an email, click, set their password, they're in. Roles:

Roles can be changed any time. Removing a user revokes all their sessions immediately.

Inviting Claude Code (MCP)

Want Claude Code (or Cursor, or Claude Desktop) to drive ptai? Run:

ptai mcp setup

This drops the right MCP entry into your Claude Code or Claude Desktop config. Then in Claude Code:

"Use ptai to run a recon engagement against testphp.vulnweb.com and summarize what you find."

It works because the CLI and the MCP server share the same code path. Same agents, same orchestrator, same database, same reports.

What if I run into a problem

Three lanes:

  1. Bug or unexpected behaviour: file a GitHub issue. The OSS team triages within 24 hours weekdays.
  2. "How do I…" question: ask in Discussions. Faster than support email for technical questions.
  3. Account, billing, or anything you don't want public: email [email protected]. Reply target during business hours: 4 hours for Pro, 1 hour for Team, immediate for Enterprise.

For an outage, check status.pentestai.xyz first. We'll have a banner before you finish typing the support email.

Just the CLI

If you're not paying and just want the OSS CLI:

pip install ptai
export ANTHROPIC_API_KEY=sk-ant-...    # or any provider above
ptai start http://your-authorized-target

That's it. No account, no signup, no telemetry. Reports are written to ./reports/. Findings DB is ./pentest_findings.db. Both are yours.

What ptai will not do

So you know what you're getting:

Where to next

Found a typo? If anything in this guide is wrong, out of date, or makes you feel stupid for asking, file an issue or open a PR. The doc lives at docs/getting-started.md in the public repo.