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.

From an assistant, a project is how an agent is made: projects_plan previews the project and its price, and after the user's OK projects_create with the agent's first task as brief creates the project and starts that task. The answer names the project's page in the app as url, with the agent and its first chat. projects_list returns one page at a time: pass limit and cursor; the answer carries count and next, which goes back as cursor until it is null.

Project workspace​

Open an app, page or fleet from Projects. The project picker at the top searches your project list as you type and switches the whole workspace. New project opens a name, template and budget, then a plan to review before creation.

The left column lists the project's agents, with the master first. The centre shows the resource graph, storage, money and errors; money includes the project agent's chats and the subagents it starts. The graph and the project's Triggers section show what starts its agents: schedules and events. The master conversation stays beside it; on a small screen it appears above the graph. Select another agent to read its conversation in place, use History for earlier runs and Back to master to return to the main chat.

An app or page uses its project agent; a fleet uses its lead. Ask the master to build or change the project, and review its proposed plan before applying it. Open full conversation opens the agent's complete run view when needed.

Use the Projects menu in the top bar to reach Home, Models, MCPs/Tools and the other sections. Your account menu is on the right; the project keeps the full page width for its agents, graph and conversation. Drag the divider beside the chat to adjust its width; your browser remembers the setting. You can also focus the divider and use the arrow keys, or double-click it to reset.

Choose effort without starting a task​

Choose a model from list_agent_models or GET /api/v1/agents/llm-models/. If it lists effort_options, select one as effort; an empty list means omit it. Omitted, null or blank effort keeps the default. An explicit level is trimmed and lowercased. Without model, an explicit effort also binds the current project default model to the plan.

Preview with projects_plan: use template: "empty", a name, a budget and the chosen model and effort. Omit both brief and first_message. The plan starts nothing. After you confirm it, pass the same fields and its plan_token to projects_create with a stable operation_key. This creates a private project and saves its agent's model and effort without starting a task or chat. The REST response omits chat; the Python result exposes made.chat as None.

REST uses POST /api/v1/agents/projects/: first without plan_token for the preview, then with that token and Idempotency-Key to create. Python has the same arguments; see the no-task example. Changing the model or explicit effort requires a new plan. After a lost creation response, keep the same request and key and inspect the returned project before deciding what to do next.

Start with a first task​

Through the remote Agents MCP, pass the same optional brief, model and effort to projects_plan and projects_create. The plan starts nothing. After you confirm its price and budget, creation queues the brief as the project agent's first task and returns agent and chat. Continue that conversation; do not send the brief a second time.

A brief accepts up to 65,536 UTF-8 bytes after trimming and needs a positive balance. Changing, adding or removing the brief, model or explicit effort after planning requires a new plan. A retry after a lost creation response uses the same request and operation_key.

REST uses POST /api/v1/agents/projects/: first without plan_token for the preview, then with that token and Idempotency-Key to create. first_message is a REST alias of brief; if both are nonempty, their trimmed text must match. Python uses client.projects.plan(..., brief=..., model=..., effort=...) and client.projects.create(...) with idempotency_key.

If the project is created but its first conversation cannot start, agent or chat can be null. Inspect the returned project and open its agent; do not create another project or automatically resubmit the task. Selecting only a model returns the project agent without starting a run.

Clone an app project​

Choose Clone in an app workspace, name the copy and review its budget and plan before creating it. The workspace opens the new copy when it is ready.

From your assistant, pass template: "app:<owner>/<app>" to projects_plan. Review the plan and price, then call projects_create with the same name, template and budget, its plan_token and a stable operation_key.

The copy uses your app's latest successful release and bundled source files. It starts private with new resources and its own owner-paid budget. Stored data, conversation history and personal connections are not copied. If the source changes after preview, make a new plan before creating the copy. To copy someone else's project, use its link (below) or a gallery template from projects_templates.

Cloning makes an independent project. It does not invite someone into the original project or transfer ownership. For a shareable frontend artifact, use its existing view/edit invitations or publish a link; see Frontend Artifacts.

A project shares the way an agent does, saved or not: in the project workspace choose Share, then Make public & copy link (or call projects_share). A copy gets the project's saved versions where it has them, and its agents as they are now where it has none. Anyone with the link, https://app.flymy.ai/projects/<project id>, sees what the project holds - its agents, pages, what a copy needs to connect, and its agents' chats and files, read only - and can copy it into their own account. Keep secrets and personal data out of its chats. Post the link anywhere (X, Telegram, email). Make private stops new views and copies at once; copies already made belong to the people who made them.

What a link never shows: stored data, money, budgets spent, errors and your connections or secrets. A copy takes none of those and none of the chats.

The preview. Every agent has a preview: one or two sentences on what it does, shown where people copy it - on the agent's public page and, for a lead, as the description of its project's public page and on the project's Preview tab. FlyMyAI writes it in the owner's language each time a version goes live (a freeze or a new live version), without links, ids or prices, and keeps it while the agent's goal stays the same. To write your own, open Share on the agent and edit Preview, or call update_agent with preview (REST: PATCH /api/v1/agents/tasks/<id>/, at most 280 characters). Your text stays through later freezes; save an empty one and FlyMyAI writes it again. get_agent and projects_get return preview, and preview_pinned is true while the text is yours.

Copy a project. Open the link and choose Copy project. Without an account you sign up first and come back to the same link. The copy brings the project's agents (a lead with all its subagents, all or none), its pages and its config, under your own budget. If an agent needs a tool you have not connected, the copy asks you to connect it first, as copying an agent does. When the copy is made, Finish setup with the assistant opens a chat that connects what is left - a Telegram bot token, the inputs, a schedule - with you.

From your assistant or the API:

StepAgents MCPREST
Make public or privateprojects_share (public)POST /api/v1/agents/projects/<id>/public/
See what a project holdsprojects_getGET /api/v1/agents/projects/<id>/
Copy itprojects_copy (link or id, operation_key)POST /api/v1/agents/projects/<id>/copy/ with Idempotency-Key

projects_copy answers with the new project, the agents it made and setup: needs (connections, secrets, inputs and schedules still to set) and chat, the setup assistant's chat. A tool you lack comes back as 422 missing_tools; nothing is created then. The Python SDK has client.projects.share() and client.projects.copy().

Clone an official template​

The templates at https://flymy.ai/templates/ are public projects that the FlyMy.AI team publishes and versions. Each page shows the project diagram, every agent's tools with their unit prices, the schedule and the measured setup cost. Choose Clone this template on the template's project page, or copy it from your assistant with projects_copy or copy_agent as above.

Your assistant finds them with projects_templates: its answer lists them as official, each with slug, version, title, preview, agents (how many agents a copy brings) and project (fleet:<lead id>, the id projects_copy takes). Only templates that can be copied now are listed. They are copied, not planned: pass project to projects_copy, not to projects_plan. REST: the official list of GET /api/v1/agents/projects/templates/.

A template copy is its lead agent with the lead's instructions and files - the guide, scripts and a demo input - never the author's chats, helpers, data or connections. Instead of the setup assistant it opens the lead's welcome chat: what the template does, the plan, and every question it needs in one message. Answer once; the lead then builds its helpers in your account, runs a trial, sends the first report and puts the helpers on a schedule. Nothing runs or bills until you answer. The copy answer carries template (slug, version, title, preview) and the welcome chat: execution_id for copy_agent, setup.chat for projects_copy.

Work with an external master​

Claude or Codex connected through the Agents MCP can coordinate the project. Their conversation remains in that host. Pass the cloud project agent a concrete brief: the work to own, permitted resources, budget and when to report. The cloud agent keeps the delegated conversation and can use subagents for that work. A handoff does not add spending authority beyond the user's budget and approvals.

Recover context after compaction​

Before a cloud agent replaces old turns with a summary, it saves a private checkpoint of the visible conversation. Larger checkpoints use protected file storage. The summary keeps a pointer describing when to read the archive; it also preserves references to earlier summaries.

The agent can call read_context_checkpoint with that pointer to recover a bounded chunk, then follow the returned offset for the next part. Ordinary agent chats can find prior checkpoints of the same agent with search_memory, scope_types=["task"] and namespaces=["context_checkpoints"]. Isolated Team and embedded runs keep their execution boundary and do not inherit the owner's other conversations.

Keep decisions, evidence, unfinished work and file references in task memory, including when each file should be read. Recover only what the current step needs. Old plans and summaries do not grant new approval. If an archive cannot be saved, the original context is kept.

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/.

Tools​

A project's agents use the same tool catalog as an agent in the chat. Give an agent a tool with a kind: ToolAccess resource that names the tool's slug in mcp (as search_tools or GET /api/v1/agents/tools/available/ lists it), and add that resource to the agent's tools:

resources:
serp:
kind: ToolAccess
mcp: serpapi
scout:
kind: Agent
system: ./agents/scout.md
tools: ["${resources.serp}"]

A catalog tool runs on your own connection. The plan lists under connect each tool you have not connected yet, with a link to connect it; a tool marked Ready to use runs on FlyMyAI's key and needs no connection. A budget, a rate limit, an approval or a schedule covers a tool whose actions are free, have a price bound or are priced by their duration; for a tool priced by its provider the plan refuses them and says why. apps_catalog lists the ToolAccess fields.

A frozen agent (frozen: true, which a schedule needs) keeps its steps as ordinary tool calls and has the code sandbox (execute_code) on your own runs: its schedule, the project's Start and your run_frozen. A run started by a page visitor, a trigger or another inbound channel gets no code sandbox.

Secrets​

Read an app's secret names and status, generate an absent value, or delete one. These responses contain metadata, never the stored value. Never paste a secret into chat, a prompt or an assistant's tool arguments: the owner types a value in the app, in the project's Connections tab.

Use the app's exact owner/name with the intended authenticated account. Listings include name, set, version, generated, updated_at, declared and used_by metadata. Generation preserves an existing value and its version; it does not rotate it. Delete removes the value and reports whether one existed.

ActionRemote Agents MCPREST
Read metadataapps_secrets_list with appGET /api/v1/agents/apps/secrets/?app=<owner>/<app>
Generate if absentapps_secrets_generate with app, name and optional lengthPUT /api/v1/agents/apps/secrets/ with {app, name, generate: true}
Delete a valueapps_secrets_delete with app and nameDELETE /api/v1/agents/apps/secrets/?app=<owner>/<app>&name=<name>

Generation uses 32 characters by default. For another length from 16 to 128, REST accepts generate: {length: 48}; the MCP uses length: 48. Ask the owner before generating or deleting a value. To check status, use only the listing. The Python SDK provides the same three operations through client.apps.secrets, including async counterparts.

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, flymyai 1.2.0rc8 or later):

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 has no caps: it spends without a limit until you set one.

Helper agents that the project's agent creates spend under these caps too, on their own schedules and chats as well. To change a cap without editing the config, call PATCH /api/v1/agents/projects/<id>/budget/ with an Idempotency-Key header and per_day_usd, per_week_usd or per_month_usd: an amount sets that period, null removes it and a period you leave out stays. It releases the config with only that change; what was spent stays.

A scheduled agent whose project is stopped, or whose limit is used up, does not fail: its run is skipped and shows as skipped in its runs, you get one email per limit period, and the schedule runs again once the limit resets, you raise it or you start the project.

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.

Rename or delete​

A project lists under its title, apart from its id: PATCH /api/v1/agents/projects/<id>/ with {"title": ...} renames it, and a flymy.yaml can set metadata.title. The id and the name in it stay.

DELETE /api/v1/agents/projects/<id>/ with an Idempotency-Key header deletes a project. One that never ran is removed and frees its name. One with history is archived: it stops, its schedules and triggers end, its agents are archived and it leaves your lists, while its runs and billing history stay.

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.

Pick the project agent's model​

A new project agent runs on the platform's top model. You can pick any model the platform offers for agents; it stays the agent's model, and platform updates to the agent's instructions keep it.

  • App: open the project and choose a model in the Model list under the project agent's name.
  • Agents MCP: projects_agent with model, an id from list_agent_models. Without model the agent keeps its current one.
  • REST: POST /api/v1/agents/projects/<id>/agent/ with {"model": "<id>"}; the ids come from GET /api/v1/agents/llm-models/.
  • Python SDK: client.projects.agent("app:me/paint-arena", model="gpt-6-luna").

A model the platform does not offer for agents now is refused with 400 bad_model and its reason; the agent keeps its current model.