# Configuration

<!-- Canonical: https://www.atlaso.ai/docs/configuration -->

Every knob is either a constructor kwarg or an env var. **There is no config file.**

## Environment variables

### `ATLASO_PATH`

Forces the base storage directory. Bypasses the project-marker walk. The path is expanded with `~` and resolved to absolute.

```bash
export ATLASO_PATH=/var/atlaso-data
python my_app.py
```

### `ATLASO_API_KEY`

Reserved for the v0.2 remote backend. The MCP server warns to stderr if unset; the v0.1 local backend doesn't require it.

### `ATLASO_BASE_URL`

Reserved for v0.2. Defaults to `https://api.atlaso.dev`.

### `ATLASO_ASYNC_WARNINGS`

Set to `0` / `false` / `no` / `off` to suppress `SyncInAsyncWarning` process-wide. Unknown values default to ON (no silent disable on typo).

### `USER` (read-only fallback for hooks)

The Claude Code hook scripts at `~/.atlaso/hooks/` resolve `user_id` from `$ATLASO_USER` with a fallback to the standard shell `$USER`. The SDK itself doesn't read these — they only affect hook behaviour.

### `ATLASO_TELEMETRY`

**Reserved no-op.** Has no effect in v0.1. If set truthy, atlaso emits one `UserWarning` to make the no-op explicit. The variable is name-reserved so future versions can introduce opt-in telemetry without colliding with anything you set today. **Atlaso ships zero telemetry, ever.**

## Storage path resolution

With no `path=` and no `ATLASO_PATH`, atlaso walks from cwd outward:

1. Explicit `path=` kwarg.
2. `ATLASO_PATH` env var.
3. Walk cwd → ancestors: first existing `.atlaso/` directory wins.
4. Walk cwd → ancestors: first directory with `pyproject.toml`, `package.json`, `.git`, `Cargo.toml`, or `go.mod` — creates `<root>/.atlaso/`.
5. cwd as a last resort — creates `<cwd>/.atlaso/`.

Walk stops at `$HOME` or filesystem root, depth-capped at 64. **There is no `~/.atlaso/` fallback** for field data.

```bash
atlaso doctor
# prints the resolved path + its source
```

## Transport injection

For tests, inject an `httpx.MockTransport`. Atlaso refuses an `httpx.Client` here on purpose — the client holds Authorization headers, and sharing one across tenants would leak them.

```python
import httpx
from atlaso import Memory

def stub(request: httpx.Request) -> httpx.Response:
    return httpx.Response(200, json={"ok": True})

m = Memory(transport=httpx.MockTransport(stub))
```

> `Memory(transport=httpx.Client(...))` raises `ConfigValidationError` immediately.

## Constructor knobs

```python
Memory(
    api_key=None,                  # v0.2 — env: ATLASO_API_KEY
    base_url=None,                 # v0.2 — env: ATLASO_BASE_URL
    path=None,                     # storage — env: ATLASO_PATH
    validate_user_id=None,         # callable; raise to block
    timeout=10.0,
    max_retries=2,
    suppress_async_warning=None,   # env: ATLASO_ASYNC_WARNINGS
    transport=None,
)
```

---

<!-- atlaso:doc-trailer -->
**Source:** <https://www.atlaso.ai/docs/configuration>  
**Edit on GitHub:** <https://github.com/imashishkh21/atlaso/tree/main/docs/configuration.md>  
**Updated:** 2026-05-12