Atellagent Client

Atellagent Client is the local enforcement component of Agent Authority. It extends Agent Authority into customer-operated runtimes, where it can request decisions and enforce approved tool actions without exposing the runtime to inbound Atellagent traffic. It is public client code: it implements documented client contracts and local verification, not managed-service policy implementation.

Agent Authority defines the policy and decision model across hosted workspaces and participating external runtimes. Atellagent Client is the supported local path for customer-owned Python agents, provider SDK calls, MCP peers, private bridges, and documented Codex and Claude Code hook boundaries. Gemini CLI is present as a preview adapter but is not a supported release host yet. Coverage remains specific to the selected integration surface and the host events it exposes.

Start here

Install the core client for CPython 3.11:

pip install atellagent-client

Check the installation trust prerequisites before installing.

Install only the provider extra used by a customer adapter, for example atellagent-client[openai], atellagent-client[google], or atellagent-client[anthropic]. See the documentation index for every supported extra and integration path.

Choose placement

This package documents the connected and customer-owned adapter paths. It does not alter hosted runtime architecture.

Choose an integration surface

hook and provider_proxy are integration surfaces, not additional policy modes. The actual connected MCP tool boundary is distinct from the MCP compatibility proxies; see the linked guides before selecting one.

For Codex, Claude Code or an existing local MCP server on macOS or Windows, start with the desktop app guide. The local device service guide covers the same setup through the CLI and running approved connections under your user account. Setup uses browser authorization and explicit organization selection, not downloaded identity configuration or copied tokens. The Gemini CLI adapter is not release-supported yet. Use atellagent-cli discover for a human-readable, read-only inventory of your Codex and Claude Code settings; add --project /path/to/project to include one selected project, or --json for redacted structured output. Discovery does not connect to or approve MCP servers. Enroll the device once; Codex and Claude Code under the same OS user share that device, but each connection requires its own approval and owner consent. Device reporting works without an agent connection. The local service reports a bounded current-user discovery snapshot by default; the user can opt out per installation. See the background-service guide for the report contents and opt-out behavior.

Choose model governance

Neither mode silently falls back to the other. A host submitted-prompt hook is turn_entry coverage, not a claim to observe every subsequent model request. See provider sessions and external hosts.

Choose identity

The mode is provisioned with the connected boundary and is not a local configuration switch. Standard Claude Code and Codex hooks use boundary_identity_only.

Setup and operation

For native hosts, begin device setup and follow the reviewed request flow in the service guide. For SDK and server/container deployments, use workload setup: sign in through the browser link/code, select an organization, submit a request and obtain administrator approval.

Keys stay local. Approved settings and credentials are delivered into private managed state; runtime commands resume its exact request ID. Workloads operate with their machine identity, while native agents use reviewed user delegation. Ordinary runtime requests do not initiate browser sign-in. Native delegation normally continues until revoked; explicit authorization expiry, access removal and current policy still apply. Browser logout alone does not end an approved native connection or workload.

For a portable container deployment, use the artifact-first image only by digest; attended setup and runtime are separate invocations. See the Docker guide.

Public-contract boundary

Use the documented exports and guides only. Avoid underscored modules and implementation modules not named as supported entry points. Public API compatibility follows the compatibility policy; report a security issue through SECURITY.md without including credentials or customer data.

Protect your MCP server

Enterprise MCP adds a direct intake to the same connected MCP runtime and mounted handler. Your server authenticates callers; Atellagent authorizes each action before execution. External MCP traffic is blocked by default. An administrator configures Allow external MCP traffic during setup or in Policies → Rules → Connection controls. The External MCP traffic shortcut in Runtimes & Integrations edits the same setting.

Governed-action allowance

Administrators can stop eligible clients or explicitly permit local continuation after their governed-action allowance is exhausted. Passthrough pauses central policy checks and per-action cloud audit. See the quota control contract for eligibility, local restrictions and recovery.