Metadata-Version: 2.4
Name: agent2you
Version: 3.0.7
Summary: Deploy a team of chat-resident AI agents from declarative manifests: Hermes + litellm + acp2api + subscription coding CLIs, one container per agent.
Author: neprel
License-Expression: MIT
Project-URL: Homepage, https://github.com/neprel/agent2you
Project-URL: Repository, https://github.com/neprel/agent2you
Project-URL: Issues, https://github.com/neprel/agent2you/issues
Keywords: agents,ai,hermes,acp,mattermost,docker,fleet,claude-code,codex
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: croniter<7,>=6
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# agent2you

agent2you deploys persistent AI colleagues into the messenger where your team
already works. Each agent gets its own container, workspace, memory and coding
subscription login; reviewed YAML manifests render the complete runtime. A
supervisor agent owns the fleet repository and prepares new hires while the
operator keeps control of accounts, images and starts.

```mermaid
flowchart LR
    Human[Human in chat] --> Gateway[Hermes gateway]
    Gateway --> Core[LiteLLM routing]
    Core --> Bridge[ACP bridge]
    Bridge --> Brains[Subscription coding CLIs]
    Core --> APIs[Optional API or local models]
    Gateway --> Memory[Personal memory]
    Agent[Supervisor agent] --> Manifests[Fleet manifests]
    Manifests --> Render[a2y render]
    Render --> Runtime[Reviewable deploy tree]
    Runtime --> Gateway
```

## Start

The shortest path is to hand the bootloader to a coding agent:

```sh
uvx agent2you bootstrap
```

It interviews you about the chat platform, agents, brains and secret source,
then delegates deterministic work to the CLI. If you prefer to inspect a whole
configuration first, read the [two-agent Telegram example](examples/minimal/).

### Pull the published base

This path downloads the signed universal runtime and builds only local toolkit
layers. Replace the two Telegram placeholders after copying the example; the
rendered `example.env` names every required value.

```sh
git clone --depth=1 https://github.com/neprel/agent2you.git
cd agent2you/examples/minimal
uvx agent2you render
cp deploy/example.env deploy/.env
${EDITOR:-vi} deploy/.env
uvx agent2you build
uvx agent2you onboard supervisor
uvx agent2you onboard researcher
uvx agent2you up
uvx agent2you doctor
```

`image.base` in the example selects `ghcr.io/neprel/agent2you:3.0.5`; replace
the tag with its digest for a fully reproducible fleet.

### Build everything yourself

`init` vendors the complete editable image context. Omit `image.base`, describe
the fleet, then render and build on the machine that runs the containers.

```sh
uvx agent2you init my-fleet --name my-fleet --agent supervisor
cd my-fleet
${EDITOR:-vi} fleet.yaml agents/supervisor/agent.yaml agents/supervisor/SOUL.md
uvx agent2you render
cp deploy/example.env deploy/.env
${EDITOR:-vi} deploy/.env
uvx agent2you build --parallel 2
uvx agent2you onboard supervisor
uvx agent2you up
uvx agent2you doctor --probe-brains
```

The bootloader explains the human-only platform and device-code steps. Never
put a provider key in `OPENAI_API_KEY`; the default topology spends the coding
CLI subscriptions you sign into, and direct API fallback uses separately named
variables. See [subscription and API posture](docs/subscriptions.md).

## What you get

- one coding session per chat thread, live progress, steering and bounded resume;
- one constant model endpoint with ordered subscription/API/local fallback;
- embedded personal memory plus reviewable git repositories for shared knowledge;
- deterministic generated configuration, strict validation and offline doctor;
- explicit secret providers, portable credential-bearing backups and logout;
- opt-in office, voice, browser, transcription, calendar, GPU and language toolkits;
- native AMD64/ARM64 images, or a fully editable local build.

Heavy capabilities remain agent-level. The shipped language-platform toolkits
are real build recipes, not placeholders:

```yaml
image:
  toolkits: [go, rust, java, dotnet]  # fleet-wide compiler/runtime layer

# Or in one agents/<name>/agent.yaml:
toolkits: [browser, office]           # only this agent gets Chromium + office conversion
browser: {novnc: true}
```

Large transcription weights live in the host-owned `volumes/models/` store and
mount read-only; they never enter the reusable base. System tools unavailable in
a chat are added by the supervisor as a toolkit—runtime sudo is intentionally
absent.

## Use cases

- **Virtual department in a messenger:** specialized colleagues share rooms,
  delegate with explicit mentions and retain their own continuity. See the
  [botless marketing-department demo](https://github.com/neprel/agent2you-demo-agents).
- **One personal assistant:** run one supervisor with Telegram, local text or
  embedded memory, and only the repositories/capabilities it needs.
- **Supervisor-managed delivery team:** the supervisor owns the fleet repo,
  interviews for a role, runs `agent add`, and hands image/start work back to
  the operator while each agent uses its own subscription account.

Project knowledge has four deliberately different homes:

- OpenWiki maintains reviewable knowledge repositories;
- Spec Kit maintains specs and tasks in working repositories;
- HINT records granular decisions beside code;
- personal memory recalls agent-specific conversation history.

## Commands

The table is checked against the argument-parser registry in CI.

<!-- commands:start -->
| command | use |
| --- | --- |
| `a2y bootstrap` | Print the infrastructure interview/runbook. |
| `a2y init` | Create a fleet workspace and vendor pack-owned files. |
| `a2y agent add` | Add an agent non-interactively. |
| `a2y agent list` | List roles, chains and access. |
| `a2y agent remove` | Remove identity; park state unless explicitly purged. |
| `a2y render` | Render manifests deterministically into `deploy/`. |
| `a2y build` | Pull/build the base and local toolkit layers. |
| `a2y up` | Prepare volumes and start selected agents. |
| `a2y down` | Stop selected agents. |
| `a2y doctor` | Check manifests, state, credentials and optional live paths. |
| `a2y upgrade` | Three-way refresh pack-owned workspace files. |
| `a2y backup` | Archive credential-bearing agent state. |
| `a2y restore` | Restore one agent archive. |
| `a2y rebuild` | Snapshot, rebuild, recreate and verify. |
| `a2y models pull` | Download declared large models and verify offline loading. |
| `a2y key show` | Print an agent's public machine identity. |
| `a2y key rotate` | Replace an agent SSH identity. |
| `a2y onboard` | Resume the verified platform/brain sign-in checklist. |
| `a2y logout` | Remove subscription credentials and print server-side follow-ups. |
| `a2y secrets edit` | Edit the encrypted SOPS secret source. |
| `a2y knowledge remember` | Add a fact to local text memory. |
| `a2y knowledge retract` | Supersede a local-memory fact. |
| `a2y duties templates` | Print recurring cost/quota/gardener templates. |
| `a2y testguard status` | Print measured spend and fuse state for a live test. |
| `a2y drill` | Run bounded behavior contracts through real chat. |
| `a2y rotate` | Rotate internal secrets or stop at a provider-owned step. |
| `a2y outdated` | Report newer pack/image pins without changing files. |
| `a2y auth` | Print legacy brain sign-in guidance. |
| `a2y provision` | Print platform provisioning instructions. |
<!-- commands:end -->

Live development and acceptance runs use a mechanical token fuse; see
[subscription-safe testing](docs/testing.md). New workspaces start with a
200,000-token development budget. Remove `testing:` only when the workspace is
promoted to production.

## Distribution and trust

Tagged releases publish the Python package, generated-notes GitHub Release and
signed native AMD64/ARM64 base at `ghcr.io/neprel/agent2you`. The public base
contains the universal runtime—not fleet toolkits, identity or secrets. Fleets
may pin it by digest through `image.base` or omit that key and build the vendored
Dockerfile locally; verification commands and the release gates are in
[operations](docs/operations.md#release-and-image-compatibility).

## Reference

- [complete manifest schema](docs/schema.md)
- [architecture and data flow](docs/architecture.md)
- [symptom-first troubleshooting](docs/troubleshooting.md)
- [provisioning](docs/provisioning.md) and [secrets](docs/secrets.md)
- [operations, backup and upgrades](docs/operations.md)
- [toolkits, platforms and executors](docs/extending.md)
- [hiring through the supervisor](docs/hiring.md)
- [subscription and API posture](docs/subscriptions.md)
- [image-size ledger](docs/image-size.md)

## License

MIT
