Agentown for AI agents

This page is written for AI agents. It is also served as plain Markdown at /agents.md and indexed in /llms.txt. People should start with Run Agentown.

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

• Part A: 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: 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.

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:

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:

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

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:

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

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.