# Overview > What ATI exposes (`ati run`, provider catalog, proxy mode), runtime assumptions (`~/.ati/`, `ATI_PROXY_URL`), and the shortest path from `ati init` to a scoped tool call. - Repository: Parcha-ai/ati - GitHub: https://github.com/Parcha-ai/ati - Human docs: https://grok-wiki.com/public/docs/parcha-ai-ati-a9d4398f11fa - Complete Markdown: https://grok-wiki.com/public/docs/parcha-ai-ati-a9d4398f11fa/llms-full.txt ## Source Files - `README.md` - `AGENTS.md` - `src/main.rs` - `src/cli/call.rs` - `Cargo.toml` - `src/lib.rs` --- --- title: "Overview" description: "What ATI exposes (`ati run`, provider catalog, proxy mode), runtime assumptions (`~/.ati/`, `ATI_PROXY_URL`), and the shortest path from `ati init` to a scoped tool call." --- ATI is a single Rust binary (`ati`, crate `agent-tools-interface`) that exposes one execution surface for agents: `ati run [--key value]`. The binary loads provider manifests from the ATI directory, resolves credentials from a local keyring or a remote proxy, dispatches by handler type (`http`, `openapi`, `mcp`, `cli`, `file_manager`, `passthrough`), and formats results as JSON, table, or text. When `ATI_PROXY_URL` is set, the same command forwards to `POST /call` on an `ati proxy` server that holds secrets and enforces JWT scopes. ## What ATI exposes | Surface | Role | |--------|------| | `ati run` | Execute a named tool with `--key value` arguments (flags without values become `true`) | | `ati tool` | List, search (`ati tool search`), and inspect schemas (`ati tool info`) | | `ati provider` | Import OpenAPI specs, add MCP/CLI providers, list/remove manifests | | `ati assist` | LLM-guided discovery — which tools and exact `ati run` commands | | `ati skill` / `ati skillati` | Methodology docs, install, resolve, remote GCS fetch | | `ati key` / `ati token` | Credential storage and JWT lifecycle | | `ati proxy` | Axum server: `/call`, `/mcp`, `/help`, `/tools`, `/skills`, `/skillati/*`, `/health` | | `ati init` | Create `~/.ati/` layout (`manifests/`, `specs/`, `skills/`, `config.toml`) | The clap entry point in `src/main.rs` wires subcommands to `src/cli/*` handlers. The library crate (`src/lib.rs`) publishes `core`, `proxy`, and `security` for embedding and integration tests; CLI formatting and provider glue stay binary-only. ### Global CLI behavior Default `json`. Also set via `ATI_OUTPUT` or alias `--format`. Shorthand for `--output json`. When placed after tool args on `ati run`, clap may swallow it via `trailing_var_arg`; `call.rs` re-detects `-J`/`--json` for output formatting. Enables debug tracing (`RUST_LOG` still controls subscriber filters). ## Runtime layout ATI state lives under one directory, resolved in order: `ATI_DIR` → `$HOME/.ati` → `.ati`. :::files ~/.ati/ ├── manifests/ # Provider catalog (*.toml); repo ships curated manifests ├── specs/ # OpenAPI JSON referenced by openapi handlers ├── skills/ # Installed SKILL.md methodology docs ├── config.toml # Proxy/JWT settings (created by `ati init --proxy`) ├── credentials # Dev-mode plaintext keys (optional) ├── keyring.enc # AES-256-GCM encrypted keys (local mode) └── (jwt-*.pem) # ES256 key pair when `ati init --proxy --es256` ::: `ati init` explicitly creates `manifests/`, `specs/`, and `skills/`. Many commands also call `ensure_ati_dir()` to lazily create the same tree on first use. The repository bundles curated manifests (for example `clinicaltrials`, `finnhub`, `github-mcp`, `deepwiki-mcp`, `google-workspace`, `crossref`, `hackernews`) under `manifests/`. User-added providers land in `~/.ati/manifests/` via `ati provider import-openapi`, `add-mcp`, or `add-cli`. ## Execution modes `ati run` auto-detects mode from the environment — agents keep the same command shape. ```mermaid flowchart TB subgraph cli["ati run (src/cli/call.rs)"] RUN[parse_tool_args] FM{file_manager tool?} PROXY{ATI_PROXY_URL set?} LOCAL[execute_local] PX[execute_via_proxy → POST /call] FMEXEC[execute_file_manager] end subgraph local["Local mode"] REG[ManifestRegistry::load manifests/] KR[load_keyring: keyring.enc → credentials → empty] SCOPE[load_local_scopes_from_env] DISP{provider.handler} HTTP[core/http + generic] MCP[core/mcp_client] CLI[core/cli_executor] end subgraph proxy["Proxy mode"] JWT[ATI_SESSION_TOKEN Bearer] PSERVER[ati proxy: keyring + scopes + upstream] end RUN --> FM FM -->|yes| FMEXEC FM -->|no| PROXY PROXY -->|yes| PX --> PSERVER PROXY -->|no| LOCAL --> REG --> KR --> SCOPE --> DISP DISP --> HTTP DISP --> MCP DISP --> CLI ``` | Mode | Trigger | Where credentials live | Typical use | |------|---------|------------------------|-------------| | Dev | No `keyring.enc`; `~/.ati/credentials` or `ati key set` | Plaintext `credentials` (0600) | Local development | | Local | `keyring.enc` + optional `/run/ati/.key` one-shot session key | mlock'd keyring in-process | Sandboxed agents with encrypted keyring | | Proxy | `ATI_PROXY_URL` set | Proxy host `keyring.enc` / `--env-keys` | Untrusted sandboxes — zero keys in agent VM | In local mode, if JWT validation env vars are configured (`ATI_JWT_PUBLIC_KEY`, `ATI_JWT_SECRET`, etc.), `ATI_SESSION_TOKEN` becomes mandatory and scopes are enforced from claims. Without JWT config, local mode stays unrestricted for development. Proxy client requests use `Authorization: Bearer` from `ATI_SESSION_TOKEN` (with `ATI_SESSION_TOKEN_FILE` and `/run/ati/session_token` fallbacks per `src/proxy/client.rs`). ## Provider catalog and tool naming Each `[provider]` block in a manifest TOML defines auth, `handler`, and transport-specific fields. Tools are either hand-written `[[tools]]` entries (HTTP) or auto-discovered (OpenAPI `tools/list`, MCP `tools/list`). | Handler | Discovery | Example tool name | |---------|-----------|-------------------| | `http` (default) | `[[tools]]` in manifest | `medical_search` | | `openapi` | Spec operations at registry load | `finnhub:quote` | | `mcp` | Live `tools/list` on first use | `github:search_repositories` | | `cli` | Single wrapper per provider | `gh` (args after `--`) | | `file_manager` | Built-in virtual provider | `file_manager:download` | | `passthrough` | Proxy edge reverse-proxy routes | Manifest-defined paths | MCP and OpenAPI tools use the `provider:tool` separator (`TOOL_SEP` = `:`). Dispatch strips the provider prefix before calling the upstream MCP server. ## Shortest path: init to scoped tool call ```bash # Pre-built binary or: cargo install agent-tools-interface ati init ``` Creates `~/.ati/manifests`, `specs`, `skills`, and a starter `config.toml` (unless you pass `--proxy` to generate JWT material). ```bash # No API key — ClinicalTrials.gov ships in-repo; import refreshes user manifest ati provider import-openapi https://clinicaltrials.gov/api/v2/openapi.json # Or use a bundled manifest already under manifests/ after copying to ~/.ati ``` ```bash ati key set finnhub_api_key "your-key" ati key list # values masked ``` Skip when `auth_type = "none"`. ```bash ati tool list --provider clinicaltrials ati tool info clinicaltrials:searchStudies ati run clinicaltrials:searchStudies --query.term "cancer" --pageSize 3 ``` ```bash ati init --proxy # or --proxy --es256 ati token issue --sub agent-1 --scope "tool:clinicaltrials:* help" --ttl 3600 export ATI_SESSION_TOKEN="" export ATI_PROXY_URL=http://127.0.0.1:8090 # proxy mode ati proxy --port 8090 --ati-dir ~/.ati # on the secrets host ati run clinicaltrials:searchStudies --query.term "cancer" # allowed ati run finnhub:quote --symbol AAPL # denied if not in scope ``` Verify success with `ati tool info ` (schema + usage line) or `ati --output json run ...` for structured output. ## Tool discovery tiers Agents typically combine three discovery paths before `ati run`: 1. **`ati tool search `** — Offline fuzzy match across names, descriptions, tags, and hints. 2. **`ati tool info `** — Full input schema, endpoint, handler, and example command. 3. **`ati assist ""`** — LLM context over visible tools (and resolved skills); requires `help` scope in proxy mode when JWT is enforced. In proxy mode, `ati tool list`, `ati tool search`, and `ati assist` can route to the proxy so listings respect JWT scopes (same as `/tools` on the server). ## Proxy mode contract Set two variables in the agent sandbox: | Variable | Purpose | |----------|---------| | `ATI_PROXY_URL` | Base URL (e.g. `http://proxy:8090`) — switches `ati run` to proxy client | | `ATI_SESSION_TOKEN` | Bearer JWT with `scope` claim (`tool:…`, `skill:…`, `help`, `*`) | The proxy executes `POST /call` with `{ "tool_name", "args" }` (and optional `raw_args` for CLI tools). It loads manifests and keyring from `--ati-dir`, validates JWT when configured, injects auth, and calls upstream HTTP/MCP/CLI. When JWT validation is configured on the proxy, missing or invalid `ATI_SESSION_TOKEN` is rejected — there is no partial trust. Unconfigured JWT on the proxy keeps dev-style open access. ## Security and credentials (summary) Local `load_keyring` cascades: sealed `keyring.enc` (session key at `ATI_KEY_FILE`, default `/run/ati/.key`) → persistent local key → plaintext `credentials` → empty keyring. OAuth2 tokens and generated credentials use an in-memory `AuthCache` during the call. Proxy mode keeps API keys off the agent filesystem entirely; only manifests (no secrets) and the session JWT need to be provisioned into the sandbox. ## Related pages Pre-built musl binaries, `cargo install`, Docker, and platform prerequisites. End-to-end init, import, key storage, list, run, and verify. Dev vs local keyring vs proxy threat model and auto-detection. Handler types, `provider:tool` naming, and dispatch modules. `ati token` and scoped sandbox provisioning. Full subcommand tree and global flags.