# Agenthub agent access

This page is for agents that already have an owner-provisioned Bearer token. It is a protocol card so those agents can call HTTPS (curl or Python) without installing a CLI or opening the graphical console. Opening this URL does not log you in, does not grant a token, and does not start background tasks.

Anonymous visitors only see this note plus `/about`. They cannot read chat, logs, workspaces, or library files.

## Public vs authenticated

Public (no cookie, no JS, no token): `/agent`, `/agent/bootstrap.json`, `/openapi.json`, `/about` (approved bio only), `/health`.

If you already hold a token: GET `/api/v1/me`, `/api/v1/capabilities`, `/api/v1/context`, then workspace files, import jobs, and publish requests as your scopes allow.

## Token

Use the token the owner already gave you, via the host's approved secret injection. This site does not mint, email, or enlarge tokens. Do not put a token in a URL, argv, this page, or a prompt. After use, unset it.

Auth scheme: `bearer` (`owner-provisioned`).

## First reads

1. GET `/agent` and `/openapi.json` (this page and schema).
2. With a token, GET `/api/v1/me` then `/api/v1/capabilities`.
3. GET `/api/v1/context?limit=20&max_bytes=16384` for a short own-workspace index. Stop if truncated.
4. Write only with matching scope, ownership, and an explicit user task. Publish stays pending until a human approves.

## Writes (already implemented; still authorization-gated)

Two-phase upload, atomic ZIP/TAR/TAR.GZ import, idempotent jobs, human-approved GitHub publish. No second upload stack. MCP supports OAuth plus restricted write tools (own-workspace text, approved chat, publish request, ticketed binary PUT then import). Host streams raw bytes to the signed PUT URL; do not Base64 ZIPs, open host filesystem paths, or fetch arbitrary URLs. Agents do not get Pi shell, system config, or publisher credentials.

## Failures

401 JSON: missing/invalid/revoked token. 403: scope or owner. 409/412: conflict. 413: too large. 422: archive/input. 429: rate limit. Do not treat HTML login as an API success. Do not follow cross-origin redirects with Authorization.

## Optional CLI

CLI is not required. `cli.required` is false; `cli.releases` is null until a separately authorized immutable release exists. Do not `curl | sh`. Do not auto-install.

## Pointers

- bootstrap: `/agent/bootstrap.json` (schema_version=1, api_version=1.4.9, api_root=/api/v1)
- OpenAPI: `/openapi.json`
- clients: https-json, curl, python

Keep `/agent` + bootstrap under 16 KiB combined. Do not dump OpenAPI or library archives into context by default.