acira

Acira

Local policies, human review, and action history for your browser agent.

Acira adds a protection layer to an existing asynchronous Playwright or browser-use application. Keep your browser workflow and model configuration; define which supported actions to allow, review, or block through local policy files.

• Policies: bundled protections and specific rules for captured website targets.
• Human review: approve one supported action, with its target and operation details.
• Local history: inspect recorded decisions and observed browser outcomes.
• Optional dashboard: manage projects, agents, policies, and reviews on your computer.
• Capture extension: select a website target and export a policy without activating it.

The base SDK needs no model, API key, or cloud account. Playwright and browser-use are separate dependencies; your existing agent may have its own model requirements.

Setup guide · Playwright guide · browser-use guide · Protection boundaries

Version scope

This guide describes Acira 0.1.1. pip install acira installs the latest published PyPI version, which may be older than these instructions. Match the guide to the version you install; 0.1.0 has versioned installation instructions. Check your project's framework compatibility with acira doctor.

Acira 0.1.1's supported release scope is macOS with standard CPython 3.11–3.15. Linux and Windows release support is deferred; their code, tests and contributor examples remain in the project.

Installation

Requires Python 3.11 or newer. Use your project's virtual environment and see compatibility for integration and platform boundaries.

If Playwright is already installed, keep your compatible installation and skip the first two commands. For a new Playwright project, install the official framework and its Chromium build, then add Acira to the same environment:

python -m pip install playwright==1.63.0
python -m playwright install chromium
python -m pip install acira
python -m pip check

See Playwright's installation guide for platform prerequisites. Installing base Acira does not install a browser or model. The optional acira[playwright] extra installs the Python framework alongside Acira; the browser installation remains explicit.

From your existing project directory:

acira init
acira doctor

The initialization wizard creates acira.json and policy folders, lets you choose starter protections, and prints the integration snippet. It does not rewrite your application. acira doctor reports framework compatibility and configuration issues.

Protect your existing workflow

Patch Playwright inside the protection context, before launching or connecting to a browser. Keep your current workflow in the marked function:

import asyncio

from acira import protect
from playwright.async_api import async_playwright


async def run_existing_workflow(browser):
    # Replace this example with your application's existing browser code.
    page = await browser.new_page()
    await page.goto("https://example.com")
    print(await page.title())


async def main():
    async with protect() as guard:
        async with async_playwright() as playwright:
            guard.patch_playwright(playwright)
            browser = await playwright.chromium.launch()
            try:
                await run_existing_workflow(browser)
            finally:
                await browser.close()


asyncio.run(main())

Acira discovers the nearest acira.json above the working directory. To select a project explicitly, use protect(project="/path/to/project", agent="checkout").

For browser-use, select that adapter during acira init, then construct and run your existing compatible agent inside async with protect() as guard:. Keep its model, task, and browser settings. Follow the browser-use integration guide before changing framework versions. The optional acira[browser-use] extra is dependency setup for projects that need it, not a requirement for a compatible existing installation.

Read the protection and configuration updates for approval binding, terminal review behavior and legacy dashboard migration.

Policies and human review

Manage policies from your project directory:

acira policy add credentials
acira policy list
acira policy configure
acira policy validate

Bundled protections cover payments, credentials, destructive actions, downloads, and submissions. General risks can be configured to Allow, Ask, or Block; captured targets support Ask or Block. Read the policy guide for agent assignments and specific website rules.

Actions configured to Ask need an available reviewer. Without one, they block. An approval covers one attempt, and relevant target, values, and policy revision are checked again before dispatch. An observed click or HTTP response does not prove that a business transaction succeeded.

The submissions policy has a stricter boundary: GET/search forms are blocked, and other critical submissions need a supported guard.submit(...) request contract. Read the form submission guide before enabling it.

Optional dashboard and capture

acira open

The dashboard starts or reuses an authenticated loopback service for your operating system user. It brings together opted-in projects and agents, pending approvals, policy editing, and history. Project policy files remain authoritative; stopping the dashboard does not stop SDK enforcement.

Use acira init --no-dashboard or protect(dashboard=False) for file-only operation. Interactive terminal review is also available.

To capture a website-specific policy:

acira extension install

Load the printed folder through Chrome or Edge's Extensions → Developer mode → Load unpacked. Open the website, choose Acira Capture, select a target, and export its JSON. Selecting a target does not click it.

acira policy import /path/to/capture.json
acira policy validate

Dashboard pairing for direct imports is optional. Exported JSON works without it. The extension cannot capture browser-internal pages. See the capture and policy guide for setup, pairing, and updating an exported extension.

Optional demo

With Playwright and Chromium installed:

acira demo

Try reviews and blocked actions against local pages with fake data. The demo opens visible Chromium and the local dashboard, creates separate demo projects, and needs no model or paid API. It is a test drive, not an integration step. Ctrl-C stops it; acira server stop separately stops the dashboard.

acira demo --public-sites offers a limited read-only documentation-site example. acira demo --adapter browser-use is a separate optional local-model example; its model and Ollama setup are explained in the browser-use guide.

Supported boundaries

The integrations support asynchronous Chromium with Playwright 1.60.0, 1.61.0, 1.62.0, or 1.63.0, and browser-use 0.11.12 or 0.11.13. Other framework versions are rejected at attachment; Acira does not silently change an existing installation. Firefox, WebKit, and synchronous Playwright are outside the supported integration.

Protection applies to documented operations through the attached adapter. Unrelated HTTP clients, independently controlled browsers, private framework internals, and manual human actions are outside that boundary. Acira is not an operating-system sandbox and does not guarantee protection from every prompt injection or website. Unsupported mutations and operations without required evidence are blocked in protected mode. See the capability and contract guide before relying on a particular workflow.

Policy and action history is stored locally. Review images mask known sensitive controls when reliable masking is available; otherwise the image is omitted. Review your retention settings and privacy boundaries before using sensitive projects.

Troubleshooting

• Framework or dependency mismatch: run acira doctor and python -m pip check. Use a compatible project environment and review dependency changes before installing extras.
• Chromium is missing: run python -m playwright install chromium in the same environment.
• Project is not found: run from your initialized project, or pass project= to protect().
• An action is blocked: inspect its policy decision and required operation contract; approval does not enable an unsupported action.
• Dashboard connection: use acira server status. File-only enforcement remains available.

See setup and troubleshooting for detailed platform instructions.

Contributing

Small fixes, reproducible bug reports, and documentation improvements are welcome. Include the framework version and a minimal example, and remove credentials, personal data, and private policy/history files from reports.

For a development checkout, install the adapters and test dependencies, matching Chromium, and Node.js 22 or newer for extension tests:

python -m pip install ".[dev,playwright,browser-use,vertex]"
python -m playwright install chromium
python -m pytest -q

Node.js is a development test prerequisite; base SDK use does not require it. Changes to protection behavior should include tests for the relevant browser effects and failure paths. See the source repository for the project files.

License

The SDK is MIT licensed. Bundled dashboard fonts use the SIL Open Font License; their notices are included in GoogleSans-OFL.txt and GeistMono-OFL.txt.