Skip to main content
An agent bundle is a versioned definition of work that Fimo can run for your project. Use one when the goal, instructions, and access rules should live with your code and be reviewed like any other change.

​
What belongs in a bundle

New bundles live under .fimo/agents/<name>/ and contain:
  • config.yaml for the model, run limits, agent description, triggers, requested secrets, and connected tools
  • GOAL.md for the outcome and decision rules
  • Optional supporting files for the work
The top-level model field selects the supported Fimo text model for autonomous runs. New bundles set it to openai/gpt-5.6-luna; when the field is omitted, Fimo uses Luna by default. Legacy projects may use agents/<name>/ at the project root.

​
Browse and search the web

Every agent can use the built-in webFetch tool for ordinary public web pages. It returns the page as readable text, so an agent can inspect documentation, reference pages, and other public content without connecting a scraping service. It does not use a user’s login session, cookies, or private-site access. An agent that declares net:fetch in capabilities.yaml also gets webSearch, which returns ranked sources with excerpts. It can search the open web, or narrow a search with includeDomains and excludeDomains when the answer must come from specific sites. Each search runs against exactly one search service, so a failed search reports why and whether retrying can help instead of silently trying a second one. A filter the service cannot apply is reported with the results rather than dropped. Every search call also carries a usage summary of what that one search spent, so an agent can see its own cost as it works. Use the Firecrawl connection when an agent needs browser-rendered pages, screenshots, structured extraction, or other rich scraping features. The bundle is different from the ways you can start or interact with work:
  • A manual trigger starts the deployed bundle on demand.
  • A schedule trigger starts the deployed bundle on a recurring cron.
  • A webhook trigger starts the deployed bundle after an external request.
  • A scheduled command runs one project command on a cron. It is not an agent bundle.
  • Chat handles an interactive request in Studio.
  • MCP and Connections give chat, agents, or the CLI access to other tools. They do not decide when work starts.
For a side-by-side guide, see Automate your project.

​
Run a bundle manually

Add a manual trigger to config.yaml, then validate and deploy the bundle before running it:
fimo agents run starts the deployed version. It does not upload local bundle edits.

​
When a manual run is skipped

Fimo registers a bundle’s triggers when it reaches main, so a manual run can find nothing to fire for four different reasons. fimo agents run exits non-zero and names the one it hit, so you fix the right thing: Studio makes the same distinction. A bundle whose deployed config declares no manual trigger, or whose trigger has not been registered yet, has Run disabled with the reason on the button; a run you start anyway answers with the same explanation. If the organization does not have enough available AI credits to start, Fimo skips the dispatch without creating a run. The bundle and its triggers stay enabled, so a later manual, scheduled, or webhook trigger can start normally after credits become available. fimo agents run reports this as an INSUFFICIENT_CREDITS error and exits with a non-zero status, so a script can tell it apart from a run that started. In Studio, Run is unavailable while the organization has no credits left, and a run you start with credits the server cannot reserve answers with a message and a link to billing.

​
Pause or resume a bundle in Studio

Open Agents, choose Agents, then open a bundle. Its next scheduled run appears first in Runs, marked Scheduled. The row uses Next for its projected ID, a relative date such as Tomorrow at 11:00 AM, and — for changes and duration until it starts. Project managers can choose Stop to pause every future trigger and stop any planned or running work. Studio asks for confirmation before applying the change. The bundle, trigger configuration, model, capabilities, and other settings stay unchanged. While the bundle is paused, the header shows Paused and replaces the run controls with Resume. Choose Resume to make the same triggers live again with their previous settings.

​
Delete a bundle in Studio

Open Agents, choose Agents, open the bundle, then choose the actions menu (⋯) next to the run controls and select Delete agent. Studio asks for confirmation first. This is available to project managers, whether the bundle is running, idle, or paused. Deleting commits the removal of .fimo/agents/<name>/ from main, so it is the same act as deleting the folder yourself and running fimo deploy. Fimo stops anything the bundle had planned or running, then removes its registration: schedules are torn down and webhook paths are released. Runs the bundle already recorded stay in Runs, and the source history keeps the deletion as an ordinary commit. Your local checkout is not touched. Pull main — or delete .fimo/agents/<name>/ locally — before your next fimo deploy, or the deploy puts the bundle back.

​
What’s next

Create a bundle

Scaffold, describe, and validate an agent.

Schedules

Run a command on a recurring cron.

Review agent work

Answer questions and review retained changes.