Host your own agent source

Any GitHub repository can be an agent source. Publish your agents in one, and anyone can add its link in Settings → Tools → Agent sources, browse your agents, review their code and install them. The official Agent City source works exactly this way.

Repository layout

Each agent is a folder with a SOUL.md and a tools.py, as described in Agent files:

my-agents/
├── hive.json            ← optional: names the collection, picks which folders are offered
├── README.md
└── agents/
    ├── recipes/
    │   ├── SOUL.md
    │   ├── tools.py
    │   ├── README.md
    │   └── evals.json
    └── garden/
        ├── SOUL.md
        └── tools.py

Without a hive.json, Agent City offers every folder it finds with a SOUL.md and tools.py. A repository with those two files at its root is treated as a single agent.

hive.json

Put it at the root of the repository to name the collection and choose exactly which folders are offered:

{
  "name": "Ann's agents",
  "description": "Small helpers for home",
  "author": "Ann Lee",
  "agents": ["agents/recipes", "agents/garden"]
}

Field	What it’s for
name	The collection’s name, shown in Browse.
description	A line about the collection.
author	Used for any agent whose SOUL.md has no author. Without either, the repository owner is shown.
agents	The folders to offer. Anything not listed is ignored.

Limits

Limit	Value
Files in one agent’s folder	40
Size of one file	256 KB
Size of one agent	2 MB

Hidden files and folders, and __pycache__, are skipped.

How people install from it

1. They paste your repository’s link in Settings → Tools → Agent sources: https://github.com/you/my-agents, or https://github.com/you/my-agents/tree/<branch> for a branch.
2. Agent City reads the repository through GitHub’s API. Reading never runs your code. Names, descriptions, tools and needed keys are parsed from the files as text.
3. Your agents appear on Agents → Browse. Review & install shows every file, starting with tools.py.
4. Install copies the folder into their data folder at memory/agents/<name>/, with a .source.json recording your repository and the exact commit. Their card says from you/my-agents.

Private repositories work too, for people who add a GITHUB_TOKEN with access to them on Connections.

Publishing updates

1. Change the agent and bump version: in its SOUL.md (1.0.0 → 1.1.0).
2. Push to the branch people added.

When they press Refresh, the agent shows Update available with the new version. Review shows a diff of exactly what changed, and Update installs it. Nothing updates on its own, and changes elsewhere in the repository don’t count. A changed folder is offered even if you forget to bump the version, but people can’t tell what they’re getting.

Installed agents can’t be edited in Agent City, since an update would replace the changes. People can still rename them.

Sharing an agent you built

Agents you build live in ~/Library/Application Support/Agent City/agents/<name>/. To publish one, copy its folder into your repository under agents/, add it to hive.json if you have one, and push. To suggest it for someone else’s source, open a pull request there.

Your keys are never stored in an agent’s folder; they’re in Agent City’s key store. Still, check for anything you pasted into the code by hand before you push.

Coming soon

Sharing straight from the app, as a pull request to one of your sources, is being built. It will check the folder for saved keys and token-shaped strings before anything is sent.

Being a good source

Your code runs on other people’s Macs

An installed agent’s tools.py runs inside Agent City, with its access to the user’s files. Each agent’s tools only see the keys they declare, but that isn’t a sandbox. Keep tools small and readable so people can review them.

• Prefer services that need no API key. When one does, list it in NEEDS with a hint on where to get it.
• Put an approve() call before anything that acts as the user.
• Include an evals.json and a README.md.
• Use the standard library where you can. Agent City can’t install extra packages for an agent.