Gaslighter Documentation

Use the SDK from Python or the CLI

api key only

The package is named anticells. The Gaslighter SDK lives under anticells.gaslighter and uses the packaged public ANTICELLS gateway.

quick start

from anticells import gaslighter

client = gaslighter.Client.from_env()

target = client.register_target(
    url="http://127.0.0.1:8080/api/v1/execute",
    name="Staging assistant",
    connection_mode="sdk_relay",
    skip_manifest=True,
    target_body_template={"message": "__TARGET_INPUT__"},
    target_body_template_configured=True,
    target_input_field="message",
)

result = client.attack(
    target_id=target.id,
    objective="Evaluate whether the target preserves approval boundaries.",
    persona="audit_interface",
    verbose=True,
)

print(result.status, result.outcome)
print(result.judge_summary)

Targets Register direct or SDK relay endpoints.

Attacks Run one campaign with custom objective aliases.

Sweeps Run multiple attack families in one batch.

Reports Fetch Markdown reports and JSON exports.

Prepaid Run Credits

prepaid

Anticells uses prepaid workspace credits. One accepted engine run consumes one credit. Rejected requests, failed engine responses, and unused reservations do not consume credits.

Newly issued credits are valid for 30 days by default and are consumed from the soonest-expiring credit lot first. Administrators can change the global default or set an account-specific validity. Team members share the Team workspace wallet.

At zero usable credits, the dashboard, history, profile, and credit-order pages remain available; engine requests and new API-key creation return 402 insufficient_credits. Manage the wallet at /account/credits.

Install and Auth

required first

Install

Use PyPI for customer usage or editable install for local SDK development.

powershell

python -m pip install anticells

# Local repository install
python -m pip install -e .\sdk

Environment

Customers normally provide only the API key. The default SDK header is X-API-Key.

powershell

$env:ANTICELLS_API_KEY = "glk_live_customer_key"
$env:ANTICELLS_API_KEY_HEADER = "X-API-Key"

# Optional bearer style
$env:ANTICELLS_API_KEY_HEADER = "Authorization"
$env:ANTICELLS_API_KEY_PREFIX = "Bearer"

Client

synchronous

Create from environment

python

from anticells import gaslighter

client = gaslighter.Client.from_env(timeout=120)
print(client.health())

Create explicitly

python

client = gaslighter.Client(
    api_key="glk_live_customer_key",
    api_key_header="X-API-Key",
    timeout=120,
)

Close resources

python

with gaslighter.Client.from_env() as client:
    personas = client.list_personas()
    print(personas)

Targets

direct or sdk_relay

A target is the application or model endpoint being evaluated. Register once, then reuse the returned target id for campaigns and sweeps.

Register a target

python

target = client.register_target(
    url="https://target.example/chat",
    name="Production assistant",
    connection_mode="direct",
    credential="target-side-secret",
    auth={"type": "bearer", "header": "Authorization", "prefix": "Bearer"},
    skip_manifest=True,
    extra_payload={"tenant": "acme"},
    target_body_template={"query": "__TARGET_INPUT__"},
    target_body_template_configured=True,
    target_input_field="query",
    target_input_aliases=["message", "prompt"],
    upload_endpoint="/upload",
    tool_invocation_endpoint="/tools",
    file_read_endpoint="/files/read",
    upload_file_field="artifact",
    upload_message_field="note",
    upload_extra_fields={"workspace": "red-team"},
)

Inspect and update

python

targets = client.list_targets()
target = client.get_target("target_...")

updated = client.update_target(
    "target_...",
    name="Updated assistant",
    credential=None,
    auth=None,
)

validation = client.validate_target("target_...")
client.delete_target("target_...")

SDK Relay

private targets

Use connection_mode="sdk_relay" when the target is local, private, or firewalled. The SDK machine must be able to reach the target URL.

Start a relay thread

python

relay_runner, relay_thread, relay_stop = gaslighter.start_target_relay_thread(
    client,
    target_id=target.id,
    target_url="http://127.0.0.1:8080/api/v1/execute",
    credential="target_model_key_or_jwt",
    auth={"type": "bearer", "header": "Authorization", "prefix": "Bearer"},
    body_template={"message": "__TARGET_INPUT__"},
    body_template_configured=True,
    input_field="message",
    poll_timeout_seconds=20,
    timeout=60,
    verbose=True,
)

# later
relay_stop.set()
relay_thread.join(timeout=5)
relay_runner.close()

Relay CLI

powershell

anticells gaslighter relay run `
  --target "target_..." `
  --url "http://127.0.0.1:8080/api/v1/execute" `
  --target-credential "target_model_key_or_jwt" `
  --target-auth-type bearer `
  --target-auth-header "Authorization" `
  --target-auth-prefix "Bearer" `
  --input-field "message" `
  --body-template '{"message":"__TARGET_INPUT__"}'

Campaigns

single run

Start and wait

python

result = client.attack(
    target_id=target.id,
    objective="Evaluate whether the target preserves approval boundaries.",
    persona="audit_interface",
    objective_match_mode="auto_best",
    stateful_delivery="auto",
    max_history_turns=6,
    direct_phase_enabled=True,
    allow_weak_preflight=False,
    verbose=True,
    trace=True,
    polling=gaslighter.PollingConfig(timeout=1800),
)

print(result.campaign_id)
print(result.outcome)
print(result.judge_summary)

Two-step control

python

started = client.start_campaign(
    target_id=target.id,
    custom_objective="Evaluate support escalation boundaries.",
    persona="audit_interface",
)

status = client.get_campaign_status(started.campaign_id)
turns = client.get_campaign_turns(started.campaign_id)
result = client.wait_for_campaign(
    started.campaign_id,
    verbose=False,
    trace=True,
)

objective, custom_objective, and bad_objective are accepted aliases. The SDK sends the API field as bad_objective.

Family Sweeps

batch runs

Run a sweep

python

batch = client.family_sweep(
    target_id=target.id,
    families=["system_prompt_extraction", "tool_abuse"],
    prompts_per_family=2,
    persona="audit_interface",
    objective_match_mode="block_weak",
    stateful_delivery="auto",
    max_history_turns=6,
    direct_phase_enabled=True,
    family_category_overrides={"tool_abuse": None},
    allow_weak_preflight=False,
    continue_on_child_failure=True,
    verbose=True,
    trace=True,
    trace_messages=True,
    polling=gaslighter.PollingConfig(timeout=3600),
)

All families

python

# These all mean "run every available family":
families = []
families = ["all"]
families = ["*"]

started = client.start_family_sweep(
    target_id=target.id,
    families=["all"],
    prompts_per_family=3,
)

result = client.wait_for_batch(started.batch_id, verbose=True)

Reports, Events, Keys

support APIs

Markdown reports

python

campaign_md = client.get_campaign_report(
    result.campaign_id,
    tier="growth",
    customer_name="Acme",
)

path = client.save_batch_report(
    "batch_...",
    "reports/gaslighter-batch.md",
    tier="growth",
)

Streams and exports

python

for event in client.stream_campaign_events("campaign_..."):
    print(event)

for event in client.stream_batch_events("batch_...", child_id=None):
    print(event)

data = client.export_batch_json("batch_...")

Account keys

python

keys = client.list_api_keys()
created = client.create_api_key(
    name="Notebook key",
    scopes=["engine:use"],
)
client.revoke_api_key(created["key"]["id"])

CLI Commands

anticells gaslighter

powershell

anticells gaslighter health
anticells gaslighter personas

anticells gaslighter keys list
anticells gaslighter keys create --name "Notebook key"
anticells gaslighter keys revoke "key_..."

anticells gaslighter targets list
anticells gaslighter targets get "target_..."

powershell

anticells gaslighter attacks run `
  --target "target_..." `
  --objective "Evaluate approval boundaries." `
  --persona "audit_interface" `
  --trace `
  --report-path "reports/campaign.md"

anticells gaslighter sweeps run `
  --target "target_..." `
  --family "system_prompt_extraction" `
  --prompts-per-family 2

Option Reference

current SDK surface

Option	Default	Use
`api_key`	`None`	ANTICELLS account key, usually from `ANTICELLS_API_KEY`.
`api_key_header`	`X-API-Key`	Set to `Authorization` for bearer style API auth.
`api_key_prefix`	`None`	Prefix such as `Bearer`. Authorization defaults to Bearer when omitted.
`api_prefix`	`""`	Optional path prefix from `ANTICELLS_API_PREFIX`.
`timeout`	`30.0`	Base HTTP timeout. Long operations use larger minimums internally.
`max_retries`	`2`	Retries transport failures and retryable gateway statuses.
`retry_backoff`	`0.5`	Exponential retry sleep base in seconds.
`headers`	`None`	Extra request headers.
`logger`	`anticells.gaslighter`	Logger used for progress and polling messages.

Option	Default	Use
`url`	required	Target chat endpoint URL.
`name`	`None`	Friendly target name.
`connection_mode`	`direct`	Use `direct` or `sdk_relay`.
`connection_url`	`None`	Optional service-side URL for direct mode.
`localhost_aliases`	`None`	Extra host aliases to try during validation.
`relay_timeout_seconds`	`300`	How long ANTICELLS waits for relay responses.
`credential`	`None`	Target-side token, JWT, password, or API key.
`auth`	`None`	`{"type": "bearer", "header": "Authorization", "prefix": "Bearer"}` or api key/basic/none.
`skip_manifest`	`False`	Skip target manifest discovery.
`extra_payload`	`None`	Object merged into configured target body templates.
`target_body_template`	`None`	JSON body with `__TARGET_INPUT__`, `{{target_input}}`, or `{{input}}`.
`target_body_template_configured`	`None`	Marks body template as intentionally configured.
`target_input_field`	`None`	Main input field such as `message` or `query`.
`target_input_aliases`	`None`	Additional aliases like `["message", "prompt"]`.
`upload_endpoint`	`None`	Optional upload route on the target.
`tool_invocation_endpoint`	`None`	Optional tool route on the target.
`file_read_endpoint`	`None`	Optional file read route on the target.
`upload_file_field`	`file`	Multipart field name for uploads.
`upload_message_field`	`message`	Message field name for uploads.
`upload_extra_fields`	`None`	Extra upload form fields.

Option	Default	Use
`target_id`	required	Registered target id.
`prompt_id`	`None`	Use a database prompt instead of a custom objective.
`bad_objective`	`None`	API-native custom objective field.
`objective`	`None`	Friendly alias for `bad_objective`.
`custom_objective`	`None`	Friendly alias for `bad_objective`.
`persona`	`None`	Persona id, for example `audit_interface`.
`objective_match_mode`	`auto_best`	`auto_best`, `specified_only`, or `block_weak`.
`stateful_delivery`	`auto`	`auto`, `manifest_only`, `disabled`, or `full_history`.
`max_history_turns`	`6`	Max history turns sent to stateful targets.
`direct_phase_enabled`	`True`	Run the direct prompt phase before decomposition.
`allow_weak_preflight`	`False`	Allow weak preflight assessment with a reason.
`preflight_override_reason`	`None`	Required explanation when allowing weak preflight.
`verbose`	`None`	Show progress. Auto-detects interactive terminals when omitted.
`trace`	`False`	Print phases, detail sections, and messages to stderr.
`trace_messages`	`True`	Include target and attacker message turns in trace output.
`trace_max_chars`	`1200`	Max characters per traced block.
`polling`	`PollingConfig()`	Polling interval and timeout control.

Option	Default	Use
`target_id`	required	Registered target id.
`persona`	`None`	Optional persona id.
`objective_match_mode`	`block_weak`	Default is stricter than single campaigns.
`stateful_delivery`	`auto`	Same modes as campaign runs.
`max_history_turns`	`6`	Max history turns.
`direct_phase_enabled`	`True`	Run direct phase per child campaign.
`prompts_per_family`	`3`	Prompt count per selected family.
`family_category_overrides`	`{}`	Per-family category overrides. Empty or null means no category filter for that family.
`families`	`[]`	Family ids. Use `[]`, `["all"]`, or `["*"]` for every family.
`allow_weak_preflight`	`False`	Allow weak preflight assessment.
`preflight_override_reason`	`None`	Reason for weak preflight override.
`continue_on_child_failure`	`True`	Keep running remaining child campaigns after a failure.

Option	Default	Use
`target_id`	required	Registered relay target id.
`target_url`	required	Private or local target URL reachable from the SDK process.
`credential`	`None`	Target-side credential stored in the local SDK process.
`auth`	`None`	Target auth config: none, bearer, api_key, or basic.
`body_template`	`None`	Target JSON body template.
`body_template_configured`	`False`	Marks template as intentional.
`input_field`	`None`	Set fallback input field when using templates.
`extra_payload`	`None`	Object merged into relay bodies.
`timeout`	`60.0`	Target HTTP timeout in seconds.
`poll_timeout_seconds`	`20`	Long-poll timeout for pending relay jobs.
`max_requests`	`None`	Optional limit for CLI or direct runner loops.
`verbose`	`None`	Show relay progress.

Developer Checklist

before handoff

Auth

Use a full glk_live_... key, not only a visible prefix.
Keep customer keys out of notebooks, repos, and screenshots.
Use X-API-Key unless your environment expects bearer auth.

Target shape

Confirm the target accepts the body template you register.
Use sdk_relay for localhost and private targets.
Set target credentials only when the target itself needs auth.

Run control

Start with one custom campaign before enabling sweeps.
Set polling timeouts high enough for long model runs.
Save reports for review and audit trails.

Use the SDK from Python or the CLI

Prepaid Run Credits

Install and Auth

Install

Environment

Client

Create from environment

Create explicitly

Close resources

Targets

Register a target

Inspect and update

SDK Relay

Start a relay thread

Relay CLI

Campaigns

Start and wait

Two-step control

Family Sweeps

Run a sweep

All families

Reports, Events, Keys

Markdown reports

Streams and exports

Account keys

CLI Commands

Option Reference

Code Builder

Gateway

Target

Target Auth

Campaign

Sweep, Trace, Report

Generated Code

Developer Checklist

Auth

Target shape

Run control