Projects
A project is what you build and run as one unit:
- an app - one
flymy.yamland 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.
Share a project by link
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:
| Step | Agents MCP | REST |
|---|---|---|
| Make public or private | projects_share (public) | POST /api/v1/agents/projects/<id>/public/ |
| See what a project holds | projects_get | GET /api/v1/agents/projects/<id>/ |
| Copy it | projects_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.
| Action | Remote Agents MCP | REST |
|---|---|---|
| Read metadata | apps_secrets_list with app | GET /api/v1/agents/apps/secrets/?app=<owner>/<app> |
| Generate if absent | apps_secrets_generate with app, name and optional length | PUT /api/v1/agents/apps/secrets/ with {app, name, generate: true} |
| Delete a value | apps_secrets_delete with app and name | DELETE /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_agentwithmodel, an id fromlist_agent_models. Withoutmodelthe agent keeps its current one. - REST:
POST /api/v1/agents/projects/<id>/agent/with{"model": "<id>"}; the ids come fromGET /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.