Skip to main content
Create an agent bundle when you want repeatable project work to live in your repository.

​
Scaffold the bundle

create writes .fimo/agents/<name>/ in current projects. The folder includes config.yaml and GOAL.md.

​
Choose the model

The generated config.yaml uses Luna for autonomous runs:
Autonomous runs use supported Fimo text model IDs such as openai/gpt-5.6-luna. Change this top-level value to another supported Fimo text model when needed. Bundles that omit model also use Luna, so older bundles do not need a config migration. Deploy after editing config.yaml so cloud runs use the committed setting. fimo agents validate <name> and fimo validate check configured model IDs before deployment. An unsupported value points to config.yaml:model and stops validation. Remove the field to use Luna or choose a supported text model, then deploy again.

​
Set run limits

Every run is bounded by your organization’s available credits. Add a runtime block to config.yaml to give a single run a lower ceiling:
max_credits is the run’s own credit ceiling and the one limit to tune. New agents scaffolded by fimo agents create start with max_credits: 5000; raise, lower, or remove it to match the agent’s work. Leave it unset and the run may spend up to your organization’s available credits at admission. When a limit stops a run, the run page shows the reason: budget_exceeded for this run’s own credit limit, or insufficient_credits when the organization ran out of credits instead. Deploy after editing config.yaml so cloud runs use the committed limits.
max_steps is an advanced option that caps how many model steps one run may take. Most agents should leave it unset: there is no platform step cap, and credits already bound every run. Set it only when you explicitly want a step-based bound on top of max_credits. A run it stops shows the reason max_steps.

​
Write the goal

Use GOAL.md to describe the result the agent should produce. Add concrete decision rules for cases where it can proceed, needs an answer, or should leave completed work for review. Keep these outcomes distinct:
  • Ask when a missing human decision blocks correct work. The question appears in the Inbox.
  • Retain when the work is complete but a person should review it before merge.
  • Merge when the result is complete, verified, and safe to apply to the target Branch.
  • Discard when no work should be applied.
Asking ends the current invocation. Answering starts a continuation with the retained work and your response. Retaining work for review does not ask a question.

​
Add a trigger

The default template includes a manual trigger. You can also declare schedule or webhook triggers in config.yaml when the full bundle should start automatically. Use a scheduled command instead when you only need to run one existing project command on a cron.

​
Shape recurring reports when needed

You do not need to configure report formatting. By default, an agent writes a short, scannable brief for email and the Inbox, then keeps the complete evidence and analysis in the full Fimo report. If a recurring agent needs a particular audience or emphasis, add a short Reporting section to GOAL.md:
These instructions shape what the agent writes; they do not turn the report into a fixed template or place the full report in email.

​
Choose capabilities

Managed agents always receive the project-worker basics: they can read and change project files, run shell commands, and commit changes in their task Branch. Fimo owns the Branch and publication step, so you do not declare files:*, shell:exec, or git:* in capabilities.yaml. Use capabilities.yaml only for extra Fimo access, such as CMS or asset permissions, and optional web access. An absent or empty file grants no CMS or asset scope. Add net:fetch when the agent needs the web-search tool:
Namespace selectors such as cms:*, assets:*, i18n:*, and forms:* grant every current and future declarable capability in that namespace. Fimo expands them into concrete grants when a run starts, so consent and enforcement remain auditable. Use exact tokens when an agent should have a narrower scope. Every agent can read a public page with webFetch without declaring anything: Fimo retrieves the page itself and it costs nothing. net:fetch adds webSearch, which runs the query against a search service Fimo pays for, so it is opt-in rather than a baseline ability. The default template starts broad enough for a useful general-purpose agent: CMS, assets, translations, forms, analytics, deployment logs, history, previews, and read-only visibility into webhooks and schedules. Remove or narrow entries in capabilities.yaml when the agent needs less. Managed agents can also list project agents and read their run history through baseline project access. Reading runs does not require fimo:agents:run; that capability is only required to dispatch another agent. When a run needs additional public Fimo access, it may request one or more missing capabilities in a grouped Inbox question. A project member selects which capabilities to approve; selecting none is a valid denial, and a written note can explain the decision but never grants access on its own. Approved capabilities apply only to the continuation started by that answer, not to later runs. Project-worker basics are managed by Fimo and cannot be requested this way. Integration setup and OAuth are also separate from capability approval.

​
Validate and deploy

Omit the agent name to validate every bundle. Add --json when another tool needs structured validation output. Deploy before testing a changed bundle. A manual run always uses the deployed definition:

​
What’s next

Agent bundles

See where bundles fit among Fimo’s automation tools.

Runs and reports

Inspect the result of each run.

Review and Inbox

Answer blockers and decide what happens to retained work.