Skip to main content

Projects

A project is what you build and run as one unit:

  • an app - one flymy.yaml and the files it names: its pages, agents, storages and budgets (app:<you>/<name>);
  • a page published on its own (site:<page id>);
  • a fleet - a lead agent and the agents it starts (fleet:<lead agent id>);
  • a frontend artifact (artifact:<artifact id>, see Frontend Artifacts).

All of them are listed in Projects in the app, by projects_list in your assistant and by GET /api/v1/agents/projects/, with their status, money and errors.

A project is its config​

An app is its flymy.yaml. Every change - creating it, editing a file, changing a budget, stopping or starting it - is a plan and an apply of that config, and each apply leaves a release in its history. Nothing the project runs is set up beside its config.

apiVersion: flymy.ai/v1alpha1
kind: App
metadata:
  name: you/studio              # <your username>/<project name>
  description: A writer agent that keeps its scenes in the project's storage
runtime:
  compatibility_date: "2026-09-27"
access:
  visibility: private
billing:
  payer: owner
  budgets:
    project: { per_day_usd: "5", per_week_usd: "20", per_month_usd: "50" }
resources:
  scenes:                       # the project's files
    kind: Storage
    type: files
  drafts:                       # a second storage; files older than 30 days are deleted
    kind: Storage
    type: files
    retention: 30d
  writer:
    kind: Agent
    model: claude-sonnet-5
    system: ./agents/writer.md
    storage:
      scenes: read_write
      drafts: read

The files it names (here agents/writer.md) sit next to it. apps_catalog (or GET /api/v1/agents/apps/catalog/) lists every section and field this platform runs, and the ones it skips or refuses with the reason.

Storage​

A project keeps its data in one or more kind: Storage resources. A storage holds files by path, shared by the project's pages and agents and by you; which storages a project has and who may reach them is config - an agent's storage map gives it read or read_write access, and it can narrow that to some paths. A storage is made before the agents and pages that use it, its files count against its quota and show in the project, and retention deletes files older than that. A frontend artifact keeps every file of every version in its project's storage the same way.

Read and write a storage's files from your assistant with apps_storage_list, apps_storage_read, apps_storage_write and apps_storage_delete, or over REST at /api/v1/agents/apps/storage/.

Plan, then apply​

A plan creates and charges nothing. It lists what applying would create, change, keep or stop, its price (usd_per_hour) and the budgets, and returns a plan_token. Show it to the user, and after their OK apply with that plan_token and an idempotency key: exactly that plan is applied. If anything moved since the plan, the apply is refused with stale_plan - plan again.

From your assistant (the Agents MCP): projects_plan then projects_create for a new project, apps_plan then apps_apply to change one, projects_stop and projects_start to stop or start it.

From Python (the Python SDK):

from flymyai import AgentClient
from flymyai.agents import artifact_files_from_directory

client = AgentClient(api_key="fly-...")

files = artifact_files_from_directory("./studio")  # flymy.yaml at the root
plan = client.apps.plan(files=files)
print(plan.changes, plan.usd_per_hour)  # show the user before applying
release = client.apps.apply(
    files=files, plan_token=plan.plan_token, idempotency_key="studio-apply-1"
)
print(client.apps.status(release.release).status)  # applying, succeeded or failed

Over REST: POST /api/v1/agents/projects/ without a plan_token is the plan of a new project, and with it and an Idempotency-Key header the create. POST /api/v1/agents/apps/plan/ and /api/v1/agents/apps/apply/ take the files ([{path, content | content_base64}]).

Budgets​

billing.budgets.project caps what the project's budgeted parts spend per UTC day, ISO week and calendar month. Every provider and tool call of a budgeted agent reserves its price under these caps before it runs, and at a cap the next call is refused with app_budget_exhausted until the period ends. A new project gets $5 a day, $20 a week and $50 a month unless you set others.

Stop and start​

Stopping an app or a page is a release with runtime.state: stopped: its pages answer project_stopped, its budgets pause and nothing is charged while it is stopped. Its agents, storages with their files and page links are kept. Starting it shows the plan of the start and its price first, then applies that plan.

Errors and the project agent​

projects_errors (or GET /api/v1/agents/projects/<id>/errors/) is the project's errors journal over the last 30 days, newest first: failed page calls, agent runs and releases, with repeats of one error counted as one entry.

Each app or page has an agent in charge of it, created on first use (projects_agent). It reads the project's diagram, money and errors, and changes the app only by a plan you confirm in its chat.