Author a fleet

What this does

Describe the task in a private chat in the dashboard or terminal. agentsfleet drafts the setup for you to review and save. A draft is private to the person who started it. Saving creates one fleet in the workspace. Publishing the setup to the Fleet library is a separate choice. A fleet’s setup is one Definition: a JSON document holding its description, instructions, and runtime settings, including its name. The dashboard and the terminal edit the same Definition.

Before you begin

Sign in and select a workspace. Setup chat uses eligible models configured by the workspace owner or enabled as the platform default. Each model needs credentials and saved inference settings: API format, secure HTTP (HTTPS) base URL, context window, and maximum output tokens. A model listed without these settings cannot author setup. See Model providers. <MODEL_REF> is the ref of an entry returned by GET /v1/workspaces/{workspace_id}/models?purpose=authoring. Choose one whose eligibility.authoring is true. Each chat message is charged to the workspace owner’s balance. A message the balance cannot cover fails with UZ-AUTHOR-007. Settings → Billing shows settled setup-chat costs beside fleet-run costs, including paid failed attempts. Costs remain visible after you delete a private setup chat. Messages still awaiting accounting appear after their costs settle.

Steps

In the dashboard

Open New fleet in the workspace sidebar.
Check the selected model, then describe the task. New chats select an available authoring model by default. Each reply can change the draft setup.
Choose … → Edit instructions beside the chat title to review the proposed instructions. Keep chatting until the proposal matches your task.
Choose Save fleet beside the chat title. For an immediate first run, open Edit instructions → Review and run options. Enter Optional first run, then choose Save and run now.
Saving opens the fleet conversation. Its sections are Chat, Activity, and Memory.

The proposed setup creates no fleet and requests no run. Save fleet checks the current setup, then saves it. It requests no first run, but configured automatic triggers can start work once setup is ready. For a saved fleet, Edit instructions manually expands the editor below setup chat. Folding the editor keeps your unsaved text. Choose Update instructions to apply manual edits to the draft. Then choose Save fleet or Save changes. Unsaved manual edits block those save actions. An untouched editor follows changes from setup chat. If chat changes the setup during manual editing, your text remains available and a conflict blocks updates. Choose Discard manual changes and load latest to replace that local text with the current proposal. The setup chat shows a compact saved-version summary. Setup and first-run warnings remain visible when setup needs attention. Keep unfinished setup steps and schedule registration warnings in view. Use the displayed retry action when setup needs attention. To change a saved fleet, choose Edit setup in its header. A private chat opens beside the fleet conversation, based on its saved setup revision. On a phone, the editor fills the page. Describe the change, review it through Edit instructions manually, then choose Save changes in the fleet header. Your unsent message in the fleet conversation stays in place. New work uses the updated instructions; work already running keeps its current version.

Recover a stopped or failed reply

Queued… means your message is waiting to start. Working… means a reply has started. A failed reply keeps any partial text and shows its failure message. Choose Try again when available to retry the original request. Open View details for diagnostics. A retry can incur another model charge. If the provider outcome is uncertain, choose Stop authoring, then send a new message. Earlier usage stays under review, and its reserved balance can limit new work until accounting finishes. A definite credential rejection fails the reply without requiring Stop. Ask the credential owner to replace the key, or choose another available authoring model before sending a new message. A key that worked earlier can expire or be revoked. Stop keeps setup changes already accepted into the proposal. Review the current proposal before saving. Stopping setup chat leaves saved fleets running.

Find, rename, and delete setup chats

The sidebar lists saved fleets under Fleets. Select a fleet to return to its conversation. Open New fleet → Unfinished setups to resume a private unsaved chat. Only the person who started the chat can see it. A new chat is titled with the first line of your first message, cut to 100 characters. A chat started from a Definition or a Library revision takes the first line of its description. A chat with neither reads New fleet. Choose … → Rename chat above the conversation to change its title. A renamed chat keeps your title, and the saved fleet keeps its own name. You cannot rename a chat while a reply or Save is running, while earlier usage is being checked, or after the chat closes. To delete a chat, choose its delete action and confirm Delete chat. The private conversation is removed. Saved fleets keep running, and published Library revisions stay available. Hover or focus an unfinished setup row to read its full title and status. The editor identifies the saved revision beneath your changes.

In the terminal

Start a private chat with an authoring model.

agentsfleet chat --model <MODEL_REF>

/review [instance-name] · /save · /run <message> · /publish <label> · /apply · /model <ref> · /stop · /retry · /delete · /quit. Ctrl+C stops the reply being followed.
you ›

Describe the task at the you › prompt. For example: “Keep team notes in memory. Save notes when asked, and recall them before answering questions.” Ordinary text is a chat message. A line starting with / is an action.
Review the setup under the fleet name you want.
/review team-notes
The review prints the full Definition, the access it needs, and its readiness checks. Its last line reads Review digest: <DIGEST>.
Save the reviewed setup.
/save
✓ Fleet team-notes: active
/run <MESSAGE> saves and sends the fleet <MESSAGE> once. Changing the draft after a review needs a new /review before saving.

From a Definition file

Use this path for scripts and repeatable setups. A Definition draft starts without a chat message, so no authoring model call runs.

Write the Definition to a file, such as team-notes.json.

{
  "schema_version": 1,
  "description": "Saves and recalls team notes between runs.",
  "instructions_md": "Use memory_store when asked to remember a note.\nUse memory_recall before answering questions about saved notes.\nIf no matching note exists, say so instead of guessing.",
  "config": {
    "name": "team-notes",
    "x-agentsfleet": {
      "triggers": [],
      "tools": ["memory_recall", "memory_store"],
      "budget": {"daily_nanos": "1000000000"}
    }
  }
}

config.name is the fleet’s name: lowercase letters, digits, and hyphens, at most 64 characters. description is required, and every fleet list shows it. daily_nanos is a decimal string of nanodollars, so "1000000000" is one dollar a day. An empty triggers list, or none at all, means the fleet runs only when you send it a message.

Open a draft from the file and review it.

agentsfleet chat --definition team-notes.json --model <MODEL_REF> --no-input --review --name team-notes

✓ Draft <DRAFT_ID> created
Instance: team-notes
Runtime model: <varies>
<varies>
Review digest: <DIGEST>

Save the draft with the digest you reviewed. <DRAFT_ID> and <DIGEST> come from the previous output.

agentsfleet chat <DRAFT_ID> --no-input --save --name team-notes --review-digest <DIGEST>

<varies>
✓ Fleet team-notes: active

To answer mentions in a Slack channel, add a mention trigger to triggers. Answer mentions in Slack shows its fields.

Verify it works

<FLEET_ID> comes from agentsfleet list.

agentsfleet steer <FLEET_ID> "Remember that our release channel is #releases."

<varies>

After that run finishes, ask for the saved note:

agentsfleet steer <FLEET_ID> "Which channel do we use for releases?"

<varies>

Check Memory for the note and the reply for #releases. Replies and tool calls vary by model; a successful Save alone does not prove that memory was used.

Common problems

A Save that prints installing and exits with code 1 is waiting on a setup check. The lines after it name each check and its next step, such as a missing secret or a pending integration grant. Fix the check, then run agentsfleet resume <FLEET_ID>. UZ-AUTHOR-006 means the setup or its access changed after your review. Review the draft again and save with the new digest. UZ-AUTHOR-008 means the authoring model is unavailable, including a rejected credential. Repair its configuration or select another eligible model. In the terminal, run /model <MODEL_REF> to change models. If the dashboard has no eligible model, open model settings. Check the saved endpoint, API format, token limits, and credentials. Loading failures show a retry action separately from missing configuration. UZ-REQ-001 means the Definition is invalid. The detail names the field. Every runtime setting sits under config["x-agentsfleet"], and unknown keys are refused. UZ-AGT-006 means a fleet already uses the name. Review again under a different --name. UZ-AUTHOR-002 on a rename means the chat is busy or closed. Wait for the reply or the Save to finish, then rename an open chat. A retried draft creation, chat message, Save, Apply, or publish reuses its operation key. For 24 hours after the first attempt, the same key and request return the first result. The same key with a different request, or from another person, fails with 409 and UZ-AUTHOR-005. If the first attempt’s draft, message, fleet, or Library revision was deleted since, the retry fails with 410 Gone and UZ-AUTHOR-013. Start a new operation with a new key. After 24 hours, the key counts as new. A Definition holds at most 8 triggers. One webhook allows 1 through 16 event names and 1 through 64 repositories.

Remove or undo

Deleting a setup chat removes its private messages for good. Saved fleets keep running, and published Library revisions stay.

Delete a chat from Unfinished setups, with /delete in the terminal chat, or with agentsfleet chat delete <DRAFT_ID>. Saving a fleet, or saving changes to one, closes its chat. agentsfleet keeps a closed chat and its messages for 30 days, then deletes them. The chat’s expires_at field shows when. Charges for the draft’s chat messages stay in the workspace’s billing records. Delete a saved fleet only after killing it. Deletion also removes its events, grants, keys, and memory.

Start here

Work with fleets

Connect apps and tools

Memory and context

Workspace and account

Help and updates

What this does

Before you begin

Steps

In the dashboard

Recover a stopped or failed reply

Find, rename, and delete setup chats

In the terminal

From a Definition file

Verify it works

Common problems

Remove or undo

​What this does

​Before you begin

​Steps

​In the dashboard

​Recover a stopped or failed reply

​Find, rename, and delete setup chats

​In the terminal

​From a Definition file

​Verify it works

​Common problems

​Remove or undo

​Related pages

What this does

Before you begin

Steps

In the dashboard

Recover a stopped or failed reply

Find, rename, and delete setup chats

In the terminal

From a Definition file

Verify it works

Common problems

Remove or undo

Related pages