Set up a fresh workstation

Use this the first time you install aeat on a clean machine. It takes you from an empty checkout to a working tool, shows you how to check what is missing, and lets you choose which optional services to turn on.

aeat works without any optional service. Google export, on-host LLM vision, and cloud LLM upload are opt-in. The core filing workflow runs with none of them.

Install the environment

Choose one of two paths: install directly on your machine, or open the project in a ready-made container.

Option A: install on your machine

Install the project and its tools in one step:

just bootstrap

This installs the Python environment, syncs every dependency group, and runs the readiness check at the end.

Option B: open in a devcontainer

The repository ships a Dockerfile and a .devcontainer/devcontainer.json with Python 3.13, uv, and headless-Chromium already installed, so you skip the manual uv sync / playwright install steps entirely.

With VS Code and the Dev Containers extension, open the project folder and choose “Reopen in Container”. The first build installs every dependency group and pre-bakes the Playwright browser; later reopens reuse the cached image.

Without VS Code, build and run the image directly:

just devcontainer-build
docker run --rm -it -v "$(pwd)":/workspace aeat-devcontainer bash

Verify the image installs cleanly and its toolchain works end to end:

just devcontainer-test

The container has no interactive display, so live AEAT browser reads run headless (AEAT_BROWSER_HEADLESS=true is set for you). Your digital certificate is personal, per-machine data — it is never baked into the image. Mount it or set AEAT_CERTIFICATE_PATH after the container starts if you need aeat app live ... inside the container; see Authenticate with AEAT.

Check what is ready

Ask aeat what is installed and what is missing:

just doctor

just doctor runs aeat config check. The report lists each external dependency, whether it is available, and the exact command to fix any gap. It also shows your profile’s capability posture. It exits with an error when a capability you turned on has a missing dependency.

Run the check directly for machine-readable output. --format json is a global flag, so it goes before the command:

aeat --format json config check

Install optional integrations

The core install is lean. Google export, the live AEAT browser, and the Anthropic-API provider are optional package extras. Install only the ones you need:

pip install "aeat-cli[google]"
pip install "aeat-cli[browser]"
pip install "aeat-cli[anthropic]"
pip install "aeat-cli[all]"

aeat config check lists each extra and prints the exact install command for any that is missing. A feature whose extra is not installed refuses with the same hint instead of failing obscurely.

Provision optional dependencies

Install the optional browser and model dependencies when you need them.

Install the Playwright browser used for live AEAT reads:

just provision

Install the on-host vision model used to read invoices. Start the Ollama server and pull the model named in the report:

ollama serve
ollama pull qwen2.5vl:3b

Install a cloud LLM provider CLI when you want cloud classification. Put its executable on PATH and sign in with that provider’s own flow. See LLM provider setup.

Run just doctor again after each change to confirm the gap is closed.

Choose your service capabilities

Each profile carries its own opt-in for three optional services. Show the resolved posture:

aeat config profile capabilities show

The three capabilities are:

  • cloud_evidence_upload — allow sending sensitive evidence to a cloud LLM provider. Off by default. Barred for gestor profiles.

  • llm_vision — read invoices with the on-host vision model. On by default.

  • google_export — export calculations to Google Sheets. On by default.

Turn a capability on or off for the active profile:

aeat config profile capabilities set llm_vision off
aeat config profile capabilities set cloud_evidence_upload on

The setup wizard also asks these questions when you create or edit a profile, so you can set them during onboarding. See Set up a profile.

Next steps