README.md

---
title: asa-api
emoji: 🔎
colorFrom: yellow
colorTo: indigo
sdk: docker
pinned: false
license: mit
---

# asa-api (Self-Hosted Docker + Tor)

`asa-api` is a self-hosted Docker API + GUI wrapper around [`asa::run_task()`](https://github.com/cjerzak/asa-software).

It uses:
- `R` + `plumber` for HTTP endpoints
- The `asa` package for orchestration (`run_task`, `run_task_batch`)
- A lightweight password-protected browser GUI at `/`
- A local Tor daemon for search/web egress inside the container

## What This Service Exposes

1. `GET /healthz`
2. `POST /v1/run` for a single prompt
3. `POST /v1/batch` for many prompts
4. `GET /` GUI page
5. `POST /gui/query` used by the GUI

## Security Model

- API bearer auth is required for `/v1/*`:
  - Include `Authorization: Bearer $ASA_API_BEARER_TOKEN`
- GUI auth is password-based:
  - `/gui/query` verifies the submitted password against an in-memory hash derived from `GUI_PASSWORD`
- The service fails closed if either auth secret env var is missing or blank.
- Auth errors are diagnostic but safe:
  - missing auth env vars return `503` with `error_code: "auth_config_missing"` and `details.missing_env_vars`
  - wrong GUI/API credentials return `401` with `error_code: "credential_mismatch"` and `details.auth_target`

## Required Environment Variables

Set these when running the container:

- `ASA_API_BEARER_TOKEN`
- `GOOGLE_API_KEY` (or the provider key you use)
- `GUI_PASSWORD`

Optional secrets / vars:

- `ASA_DEFAULT_BACKEND` (defaults to `gemini` if unset; examples: `openai`, `groq`, `anthropic`, `gemini`, `openrouter`)
- `ASA_DEFAULT_MODEL` (example: `gemini-2.5-flash`)
- `ASA_CONDA_ENV` (default: `asa_env`)
- `ASA_ENABLE_TOR` (default: `false`; set to `true` to route ASA search/web traffic through the bundled local Tor proxy)
- `ASA_USE_BROWSER_DEFAULT` (default: `false`, recommended for container stability)
- `CORS_ALLOW_ORIGIN` (default: `*`)

Provider-specific keys supported by `asa` include:

- `OPENAI_API_KEY`
- `GROQ_API_KEY`
- `ANTHROPIC_API_KEY`
- `GOOGLE_API_KEY` (or `GEMINI_API_KEY`)
- `OPENROUTER_API_KEY`
- Bedrock credentials if using `bedrock`

## API Usage

### 1) Health check

```bash
curl -s http://localhost:7860/healthz
```

### 2) Single query

```bash
curl -s http://localhost:7860/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ASA_API_BEARER_TOKEN}" \
  -d '{
    "prompt": "What is the population of Tokyo?",
    "config": {
      "backend": "gemini",
      "model": "gemini-2.5-flash"
    },
    "run": {
      "output_format": "text",
      "recursion_limit": 20
    }
  }'
```

### 3) Structured JSON output

```bash
curl -s http://localhost:7860/v1/run \
  -H "Authorization: Bearer ${ASA_API_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find Marie Curie birth year and nationality. Return JSON.",
    "run": {
      "output_format": "json"
    }
  }'
```

### 4) Batch query

```bash
curl -s http://localhost:7860/v1/batch \
  -H "Authorization: Bearer ${ASA_API_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": [
      "What is the capital of France?",
      "What is the capital of Japan?"
    ],
    "parallel": false,
    "run": {
      "output_format": "text"
    }
  }'
```

`/v1/batch` accepts only a plain JSON array of strings for `prompts`. Structured row objects that mirror upstream `asa::run_task_batch()` data-frame inputs are rejected by this adapter.

## Request Shape

### `POST /v1/run`

```json
{
  "prompt": "string, required",
  "config": {
    "...": "any asa::asa_config argument"
  },
  "run": {
    "...": "any asa::run_task argument except prompt/config/agent"
  },
  "include_raw_output": false,
  "include_trace_json": false
}
```

### `POST /v1/batch`

```json
{
  "prompts": ["required", "array", "of strings"],
  "config": {
    "...": "any asa::asa_config argument"
  },
  "run": {
    "...": "batch-compatible shared options only; single-run-only keys are rejected"
  },
  "batch": {
    "...": "any asa::run_task_batch argument except prompts/config/agent"
  },
  "parallel": false,
  "include_raw_output": false,
  "include_trace_json": false
}
```

## Future Compatibility Strategy

The adapter is intentionally resilient to `asa` changes:

- It dynamically inspects `formals(asa::asa_config)`, `formals(asa::run_task)`, and `formals(asa::run_task_batch)`.
- It only forwards request keys that exist in current function signatures.
- For `/v1/batch`, it rejects single-run-only passthrough keys instead of silently dropping them.
- This avoids hard crashes when upstream adds/removes optional args.

## GUI

- Open `/` in your browser.
- Enter `GUI_PASSWORD`.
- Enter prompt and choose output format.
- Leave `Use direct provider call (skip ASA)` unchecked to run the normal ASA agent flow.
- Check `Use direct provider call (skip ASA)` to send the prompt straight to the configured provider/model without ASA search/tool orchestration.
- Submit (Ctrl/Cmd + Enter is supported).

Notes:
- The checkbox is GUI-only; `/v1/run` and `/v1/batch` remain ASA endpoints.
- The provider/model selection stays server-side and is not user-selectable in the GUI.

## Docker Build and Runtime

The `Dockerfile` clones `asa-software` during build and installs `asa` from source.

R dependency strategy in this image:
- Base image is `rocker/r2u:24.04`.
- Core R runtime packages (`plumber`, `jsonlite`, `reticulate`, `remotes`) are installed as binary apt packages (`r-cran-*`), not compiled from CRAN source.
- This avoids source-compile failures such as `sodium` -> `plumber` install breaks.
- The Docker build pre-creates `asa_env` with pinned `python=3.12.3` and `openssl=3.0.13` before calling `asa::build_backend()`, reducing rebuild drift that can break `reticulate` SSL imports on Ubuntu 24.04 / Hugging Face rebuilds.
- Runtime linker guardrails are set so `reticulate` prefers conda environment libraries (`/opt/conda/envs/asa_env/lib` and `/opt/conda/lib`) to avoid C++ ABI loader mismatches.
- Tor is installed in the image and remains available for opt-in startup through `ASA_ENABLE_TOR=true`.

Build args:

- `ASA_SOFTWARE_REPO` (default: `https://github.com/cjerzak/asa-software`)
- `ASA_SOFTWARE_REF` (default: `main`)
- `ASA_CONDA_PYTHON_VERSION` (default: `3.12.3`)
- `ASA_CONDA_OPENSSL_VERSION` (default: `3.0.13`)

Local build:

```bash
docker build -t asa-api .
```

Local run:

```bash
docker run --rm -p 7860:7860 \
  -e ASA_API_BEARER_TOKEN=your-api-bearer-token \
  -e GOOGLE_API_KEY=... \
  -e GUI_PASSWORD=your-gui-password \
  asa-api
```

Then open:
- `http://localhost:7860/healthz`
- `http://localhost:7860/`

Tor stays off in that default run. To opt in later:

```bash
docker run --rm -p 7860:7860 \
  -e ASA_API_BEARER_TOKEN=your-api-bearer-token \
  -e GOOGLE_API_KEY=... \
  -e GUI_PASSWORD=your-gui-password \
  -e ASA_ENABLE_TOR=true \
  asa-api
```

## Tor Integration

The image still includes Tor and the Tor entrypoint integration, but `asa-api` does not activate it unless `ASA_ENABLE_TOR=true`.

When Tor is enabled, the container deploys Tor locally and exports these runtime defaults before starting `plumber`:

- `ASA_PROXY=socks5h://127.0.0.1:9050`
- `TOR_CONTROL_PORT=9051`
- `ASA_TOR_CONTROL_COOKIE=/tmp/tor/control.authcookie`

Tor scope is intentionally limited:

- Search and webpage retrieval traffic uses Tor.
- LLM provider API traffic remains direct, matching upstream `asa` behavior.
- Browser/Selenium search remains disabled by default.

Startup behavior when `ASA_ENABLE_TOR=true` is fail-closed:

- Tor must answer a probe to `https://check.torproject.org/api/ip` with `IsTor=true`.
- If the SOCKS proxy, ControlPort, or cookie setup never becomes ready, the container exits non-zero.

When `ASA_ENABLE_TOR=false`, the startup script skips Tor bootstrap and clears Tor proxy env vars before launching the API, so the agent pipeline runs direct.

`GET /healthz` now includes Tor readiness fields:

- `tor_enabled`
- `tor_ready`
- `tor_proxy`
- `tor_control_port`
- `tor_cookie_present`
- `tor_cookie_readable`

You can override the local proxy defaults if needed:

- `ASA_ENABLE_TOR`
- `ASA_PROXY`
- `TOR_CONTROL_PORT`
- `ASA_TOR_CONTROL_COOKIE`
- `ASA_TOR_PROBE_URL`
- `ASA_TOR_STARTUP_TIMEOUT_SEC`

## Notes

- Browser/Selenium tier is disabled by default (`use_browser = FALSE`) for better reliability in minimal containers.
- If you want browser tier, set `config.use_browser = true` explicitly per request and ensure supporting binaries are installed.
- If startup fails with Python import/linker errors (for example `CXXABI_1.3.15 not found`), inspect container logs and verify `GET /healthz` for `boot_error` details once the service is up.