Building your own agent

Draft help page. Shown to global admins in Settings → Agents.

The short version

• Settings → Agents → Build an agent creates a new agent in four steps: basics, programs, instructions, review. No code is involved.
• It's ready straight away. Operators see it on their Launch page.
• You choose a kind on the first step:
• Network recon does what Network enumeration does: it runs reviewed command-line programs against a target, checked on every command against the engagement's scope. It can only run the programs you tick, and it can never exploit anything: the denied patterns and the scope check are fixed.
• File analysis analyses files an operator attaches, such as a packet capture, with tshark, capinfos and suricata in a sandbox. It has no target, no network and needs no engagement. See Analysing a file. The kind is fixed once the agent is built.
• Only global admins can build or remove agents. Both actions ask for your password and a fresh 2FA code (or a passkey).

The four steps

1. Basics.
2. Kind: Network recon or File analysis.
3. Name: what people see, e.g. Web server check.
4. Short name: filled in from the name as you type, e.g. web-server-check. It's used in commands and links and can't be changed later.
5. What it does: one sentence.
6. Programs. Tick the programs it may run. Search by name or purpose. A program that isn't installed on the server is greyed out and shows the sudo apt install … command. Only reviewed programs are listed. For network recon that is the baseline recon set and the program catalog (see below). For file analysis it is the short list a developer has written option rules for (tshark, capinfos, suricata); the catalog doesn't apply to it.
7. Instructions. This is the agent's system prompt: what it's for, the steps, what to produce, and what it must not do. A template is filled in from your earlier answers. Replace the line <describe the job, step by step> with the real steps.
8. Review. Check the summary, then press Build agent and confirm with your password and 2FA code.

What a built agent can and can't do

Scope, approval and the model/caps limits come from the organisation's engagement and policy, exactly as for Network enumeration. Nothing typed into the builder can change them.

Changing a built agent

• Name, description, programs: press Edit on its card. The wizard opens filled in; the short name is fixed. It skips the instructions step. A run already going keeps what it started with; the next run uses the changes.
• Instructions: edit them in the Agent control centre further down the same page. Every edit is kept and can be reverted.

Removing a built agent

Press Remove on its card. You'll be shown what will be deleted, then asked to type DELETE and confirm with your password and 2FA code.

• Removal is permanent. It deletes the agent's runs, reports and history in everywhere.
• Kept files (Outputs) are not touched.
• You can't remove an agent while it is running anywhere, or while a team still lists it as a member. The message tells you which runs or teams.
• Hand-built agents (OSINT research, Traffic monitor) have no Remove button. They're retired from a terminal.

The program catalog

The list of programs comes from the program catalog, which an admin keeps in Controls → Edit this agent's tool allow-list (the same catalog serves every agent).

• Add a program: press Add a program. The server checks, as you type, that it is installed and allowed. Shells, interpreters, privilege and system tools (bash, python, sudo, find, rm, ssh …) can never be added. You can add blocked-argument patterns (regular expressions) to refuse options that write files or send data.
• Edit or remove: only programs an admin added. A removal is refused while an agent still has the program switched on. Every change is kept in history.
• Not installed? Anyone can file a request on the Launch page ("A command-line program installed on the server"). Admins see it under Settings → Platform with the install command to run at the server. The website never installs software.

From a terminal

sudo agenti admin agent-build tools               # the programs on offer
sudo agenti admin agent-build check  < spec.json  # validate without building
sudo agenti admin agent-build create < spec.json  # build it
sudo agenti admin agent-build preview <name>      # what removing would delete
sudo agenti admin agent-build remove  <name>      # asks you to type the name

spec.json looks like:

{"kind": "recon", "name": "web-server-check", "title": "Web server check",
 "description": "Looks at a web server's headers and open ports.",
 "programs": ["nmap", "curl", "whatweb"],
 "system_prompt": "You are Web server check. ..."}

For a file-analysis agent use "kind": "analysis" and "programs": ["tshark", "capinfos", "suricata"]; leave "kind" out and it is a recon agent.

Messages you may see

Writing an agent in code

If you need something a program list can't express (a different scope kind, a custom tool, a protocol client), write a hand-built agent. agenti new <name> scaffolds one; see docs/contributing-agents.md.