Getting Started¶

Prerequisites¶

Option	Requirement
Build from source	Rust 1.78 or later (`rustup update stable`)
Pre-built binary	None — download and run
Docker	Docker Engine 24 or later

You also need at least one LLM API key. Both agents default to claude-sonnet-4-6 (Anthropic), but each agent can be configured independently and can use any supported provider.

Install¶

Option 1 — cargo install¶

cargo install phalus

Verify the installation:

phalus --version

Option 2 — Pre-built binary¶

Download the appropriate archive from the releases page:

# Linux x86_64 example
curl -L https://github.com/phalus-project/phalus/releases/latest/download/phalus-linux-x86_64.tar.gz \
  | tar xz
sudo mv phalus /usr/local/bin/
phalus --version

Option 3 — Docker¶

docker pull ghcr.io/phalus-project/phalus:latest

For convenience, add a shell alias:

alias phalus='docker run --rm \
  -e PHALUS_LLM__AGENT_A_API_KEY \
  -e PHALUS_LLM__AGENT_B_API_KEY \
  -v "$PWD":/work -w /work \
  ghcr.io/phalus-project/phalus:latest'

Configure API Keys¶

PHALUS requires separate API keys for Agent A (Analyzer) and Agent B (Builder). Using separate keys provides stronger isolation evidence, though the same key works.

Environment variables (recommended for getting started):

export PHALUS_LLM__AGENT_A_API_KEY="sk-ant-..."
export PHALUS_LLM__AGENT_B_API_KEY="sk-ant-..."

Config file (recommended for regular use):

mkdir -p ~/.phalus
cat > ~/.phalus/config.toml <<'EOF'
[llm]
agent_a_provider = "anthropic"
agent_a_model    = "claude-sonnet-4-6"
agent_a_api_key  = "sk-ant-..."

agent_b_provider = "anthropic"
agent_b_model    = "claude-sonnet-4-6"
agent_b_api_key  = "sk-ant-..."
EOF

Verify that the configuration is loaded correctly (API keys are always redacted in this output):

phalus config

Quick Start¶

Run a single package¶

The run-one command is the fastest way to try PHALUS. It does not require a manifest file.

phalus run-one npm/left-pad@1.1.3 --license mit

The format is ecosystem/name@version. Supported ecosystems: npm, pypi, crates, go.

You should see output similar to:

OK left-pad@1.1.3

Inspect the output¶

phalus inspect ./phalus-output --csp --similarity --audit

CSP section lists the ten specification documents Agent A produced:

=== CSP Specs ===
  left-pad@1.1.3 (10 documents)
    - 01-overview.md
    - 02-api-surface.json
    - 03-behavior-spec.md
    - 04-edge-cases.md
    - 05-configuration.md
    - 06-type-definitions.d.ts
    - 07-error-catalog.md
    - 08-compatibility-notes.md
    - 09-test-scenarios.md
    - 10-metadata.json

Similarity section shows how close the generated code is to the original (lower is better for the clean room claim):

=== Similarity Reports ===
  left-pad@1.1.3:
    token_similarity: 0.1800
    name_overlap:     0.9000
    string_overlap:   0.1200
    overall_score:    0.2500
    verdict:          PASS

Note: name overlap is intentionally high — the public API names must match by design.

Audit section shows the event log for the run:

=== Audit Log ===
  [2026-03-26T10:00:00Z] seq=0 type=manifest_parsed
  [2026-03-26T10:00:01Z] seq=1 type=docs_fetched
  [2026-03-26T10:00:03Z] seq=2 type=spec_generated
  [2026-03-26T10:00:03Z] seq=3 type=firewall_crossing
  [2026-03-26T10:00:08Z] seq=4 type=implementation_generated
  [2026-03-26T10:00:09Z] seq=5 type=validation_completed

Run from a manifest¶

# Preview what would be processed
phalus plan package.json

# Run the full pipeline
phalus run package.json --license apache-2.0 --output ./output/

Output Structure¶

After a successful run, the output directory contains:

phalus-output/
├── left-pad/
│   ├── package.json
│   ├── LICENSE
│   ├── README.md
│   ├── src/
│   │   └── index.js
│   ├── test/
│   │   └── index.test.js
│   ├── validation.json          # similarity + verdict
│   └── .cleanroom/
│       └── csp/
│           ├── 01-overview.md
│           ├── 02-api-surface.json
│           └── ...
└── audit.jsonl                  # job-level audit trail