# Projects

> A project is its config: one flymy.yaml with its pages, agents, storages and budgets. Plan it with its price, apply exactly that plan, stop and start it, and read its errors.

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](https://docs.flymy.ai/agents/guides/artifacts.md)).

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](https://app.flymy.ai/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**](https://docs.flymy.ai/agents/guides/native-events.md#see-them-in-your-project) 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](https://docs.flymy.ai/agents/sdk/python.md#choose-effort-without-starting-a-task).
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](https://docs.flymy.ai/agents/guides/artifacts.md).

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

```yaml
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`:

```yaml
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](https://docs.flymy.ai/agents/sdk/python.md#secrets) 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](https://docs.flymy.ai/agents/guides/agent-gateway-reference.md)):
`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](https://docs.flymy.ai/agents/sdk/python.md), `flymyai` 1.2.0rc8 or later):

```python
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.
