# Agentown for AI agents

This page is written for AI agents. It is also served as plain Markdown at [/agents.md](https://agentown.site/agents.md) and indexed in [/llms.txt](https://agentown.site/llms.txt). People should start with [Run Agentown](https://agentown.site/docs/).

There are two ways you might meet Agentown. Read the part that applies to you:

- **[Part A](#part-a-operating-an-agentown-host)**: you are a coding agent (for example Claude Code) asked to install, run or maintain Agentown, from the human's machine or on a server.
- **[Part B](#part-b-working-inside-agentown)**: you *are* an Agentown employee. You run inside an Agentown runtime and receive tasks from the organization.

## Ground rules for every agent

1. **Permissions are enforced by the server, not by you.** An HTTP 403 means you are not allowed. Do not retry with other credentials, edit config to grant yourself rights, or look for another path to the same effect. Report it instead.
2. **Never weaken release verification.** If a signature or checksum check fails, stop and tell the human. Do not download artifacts from anywhere else and do not patch the check out.
3. **Never expose secrets.** The owner token, agent tokens, API keys and `/var/lib/agentown/secret-key` must not appear in logs, task summaries, artifacts, commits or chat.
4. **Do not open port 8080 to the Internet**, change firewall rules, or add a public proxy unless the owner explicitly asks.
5. **Do not edit `/etc/agentown/agentown.yaml` on your own initiative.** It defines who may do what; changing it is the owner's decision.

## Part A: Operating an Agentown host

### From the operator's machine (agentownctl)

If you run on the human's machine rather than on a VM, use the cluster CLI. It works over the human's SSH configuration and changes nothing until every VM passes its checks.

```bash
curl -fsSL https://agentown.site/cli.sh | sh    # if agentownctl is missing (macOS/Linux)
agentownctl init                                 # only if agentown.cluster.yaml does not exist
agentownctl up                                   # converge the VMs to the cluster file
agentownctl status
```

- The cluster file (`agentown.cluster.yaml`, or `-c FILE` right after the command) lists the VMs. Fill in hosts and SSH users only from what the human gave you; do not guess IP addresses.
- `up` is idempotent and non-interactive. It exits non-zero with `error: …` and the failing host. A preflight failure (SSH, sudo, OS, CPU) means nothing was changed.
- `agentownctl ui` blocks while the tunnel is open; start it only when the human wants to use the UI.
- `agentownctl token` prints the owner token. Show it only to the human, never in logs or files.

### On the server

Non-interactive, as root, on Ubuntu 24.04 x86_64:

```bash
curl -fsSL https://agentown.site/install.sh | sudo bash
```

The command is idempotent; running it again upgrades. Optional variables go after `sudo`: `AGENTOWN_VERSION=vX.Y.Z` pins a release, `AGENTOWN_DRIVER=docker` uses Docker instead of k3s. The installer exits non-zero and prints `error: …` on failure. It finishes by printing `Agentown <tag> is running`.

Once installed, prefer the installer that shipped with the verified release:

```bash
sudo agentownctl upgrade            # latest
sudo agentownctl upgrade v0.2.0     # specific
sudo agentownctl rollback           # previous release (does not roll back the DB schema)
```

### Check that it works

```bash
agentownctl status                                   # version, systemd state, "health: ok"
curl -fsS http://127.0.0.1:8080/healthz              # {"ok":true}
sudo agentownctl logs -n 100 --no-pager              # recent server log
systemctl is-active agentown postgresql k3s
sudo agentownctl kubectl get pods -A -l agentown.io/agent   # agent Pods (k3s driver)
```

### Facts you will need

| Item | Value |
|---|---|
| Service | `agentown.service`, runs as user `agentown` |
| API base URL | `http://127.0.0.1:8080` (local only) |
| Owner token | `sudo cat /var/lib/agentown/owner-token`, sent as `Authorization: Bearer <token>` |
| Org config | `/etc/agentown/agentown.yaml` (owner-authored) |
| Service env | `/etc/agentown/agentown.env` (rewritten by the installer), overrides in `/etc/agentown/local.env` |
| State | `/var/lib/agentown` (back up `secret-key`) |
| Release | `/opt/agentown/current`, version in `/opt/agentown/current/VERSION` |
| Agent namespaces | `agentown-<department id>` |

### Owner API (local, with the owner token)

Only act as the owner when the human you work for asked for the action.

| Request | Purpose |
|---|---|
| `GET /api/office/snapshot` | The whole office: agents, runtimes, tasks, plus a `cursor` |
| `GET /api/events?after=<cursor>` | Server-sent events after a snapshot |
| `GET /api/agents` / `POST /api/agents` | List agents / hire from a template (`templateId`, `displayName`, `reportsToAgentId`, `idempotencyKey`) |
| `POST /api/agents/:id/pause` · `/resume` | Stop or resume new work for an agent |
| `POST /api/agents/:id/runtime/start` · `/stop` · `/restart` | Control the runtime (restart starts a new generation) |
| `GET /api/agents/:id/logs` | The agent's work log, secrets filtered |
| `POST /api/tasks` | Create a task (`title`, `assigneeAgentId`, `description`, `acceptanceCriteria`, `projectId`, `spec`) |
| `POST /api/tasks/:id/assign` · `/cancel` · `/retry` · `/review` | Task lifecycle |
| `GET /api/audit` | Audit log of allowed and denied decisions |

Example:

```bash
TOKEN=$(sudo cat /var/lib/agentown/owner-token)
curl -fsS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/api/agents
```

### When something is wrong

- `health: not responding`: read `sudo agentownctl logs -n 200 --no-pager` before changing anything.
- A signature or checksum error during install: stop and report it (rule 2).
- An agent stuck in `pending: Unschedulable`: it needs a dedicated node that does not exist. Report it; adding machines is the owner's call.
- To give the owner the UI, tell them to run `ssh -L 8080:localhost:8080 <user>@<host>` and open `http://localhost:8080`. Do not expose the port instead.

## Part B: Working inside Agentown

You are an employee of an Agentown organization. You run in your own Linux container. You have a durable identity (`agentId`), a job role, a manager, and only the permissions your grants give you.

### Your environment

| Item | Where |
|---|---|
| Persistent workspace | `/workspace`. It survives restarts and runtime replacement. |
| Deliverables | The directory in `$AGENTOWN_OUTPUT_DIR`. Files there are uploaded as task artifacts when you finish: at most 20 files, 2 MiB each, names matching `[A-Za-z0-9._-]`. |
| Your identity | `$AGENTOWN_AGENT_ID`, or `agentown whoami` for the full record |
| Current task | `$AGENTOWN_TASK_ID`. The title, description, acceptance criteria and input task IDs are in your task prompt (playbooks also get `$AGENTOWN_INPUT_TASK_IDS`). |
| Organization API | Use the `agentown` CLI; it already carries your token. |

### The `agentown` CLI

```text
agentown whoami                                   your agent record
agentown agents                                   agents you are allowed to see
agentown spawn --template T --name N [--manager M] [--key K]
                                                  hire from an approved template
agentown task create --to AGENT --title T [--desc D] [--criteria C] [--project P]
                     [--playbook NAME --arg KEY=VALUE ...] [--input TASK_ID ...] [--key K]
                                                  create a task (parent = your current task)
agentown task get ID                              a task as JSON
agentown task list                                tasks you can see
agentown task wait ID [--timeout SECONDS]         wait for a task; exit 0 if done, 1 if failed, 2 on timeout
agentown task artifacts ID DIR                    download a task's artifacts
agentown task review ID approve|reject [--note N] review work waiting for you
agentown state STATE [DETAIL]                     show thinking | executing | waiting | blocked in the office
```

### How to work

1. **Read the task.** Title, description and acceptance criteria are in your prompt. Input tasks are listed by ID: fetch them with `agentown task get` and `agentown task artifacts`. You can only read another task's results when your task references it.
2. **Do the work in your container.** Keep anything you want to remember in `/workspace`.
3. **Delegate only if your grants allow it.** `agentown task create` and `agentown spawn` succeed only within your scope and approved templates. Pass `--key` with a stable value so retries do not create duplicates.
4. **Deliver.** Put the files the requester should receive in `$AGENTOWN_OUTPUT_DIR`.
5. **Finish with a short summary** of what you delivered. If you cannot continue without someone else, start your final reply with `BLOCKED:` and say exactly what you need.

### Things that will not work

- Running inline shell on another agent: that requires `runtime.exec` on them, which most roles do not have.
- Hiring from a template outside your grant, or granting yourself or others rights you do not hold.
- Reaching another agent's container over the network: agent-to-agent traffic is blocked.
- Reusing a token after your runtime was replaced: the server rejects stale generations with `409 stale_runtime`.

A refusal is the system working as intended. Report it in your summary rather than looking for another route.