> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cycls.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interface

> Branding, themes, colors, SEO, the empty-chat screen, voice input and analytics. Configure the chat product your agent ships with.

`cycls.Web` configures everything the user sees and the identity behind it. Pass
it to `@cycls.agent(web=...)`.

```python theme={null}
web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .title("Atlas")
    .brand(name="Atlas", description="Your research assistant", logo="./logo.svg")
    .colors(primary="#FF6200", secondary="#1A1A1A")
    .suggestions(True)
    .analytics(True)
)
```

![A Cycls agent empty state with brand name, description and composer](https://mintcdn.com/cycls/Vjgw_hSP7-Pr95Zb/img/agent-home.png?fit=max\&auto=format\&n=Vjgw_hSP7-Pr95Zb\&q=85\&s=41d51c128df30cb9fa730cccabecd02b)

The empty-chat screen uses the brand name, description and logo.

## Branding

```python theme={null}
web = (
    cycls.Web()
    .brand(name="Atlas", description="Your research assistant",
           logo="./icon.svg", brand="./wordmark.svg",
           og="./og.png", favicon="./favicon.svg")
    .brand("ar", name="أطلس", description="مساعدك للبحث")
)
```

| Field | Where it shows |
| - | - |
| `name` | the chat hero and the title bar |
| `description` | the line under the name on an empty chat |
| `logo` | the agent icon in the hero |
| `brand` | the wordmark in the nav bar, falling back to the Cycls mark |
| `og` | the social card image, global |
| `favicon` | the tab icon, global |

`name`, `description`, `logo` and `brand` are per locale, so call `.brand()`
again with `"ar"` for Arabic. Image paths are read at build time, SVGs inlined
and rasters embedded as data URIs, so assets do not need to ship with the
container.

## Pulling copy from a CMS

```python theme={null}
web = cycls.Web().cms(
    brand="https://cms.example.com/agents/atlas",
    explore="https://cms.example.com/agents",
    connectors="https://cms.example.com/connectors",
    token=os.environ["CMS_TOKEN"],
)
```

These are plain GET URLs returning the contract JSON. Anything declared in code
wins field by field, so a `.brand()` call overrides the CMS for exactly that
field and no other.

## Theme and colors

```python theme={null}
web = (
    cycls.Web()
    .theme("default")             # "default" or "dev"
    .colors(primary="#FF6200", secondary="#F5F5F5",
            primary_dark="#FF8A3D", secondary_dark="#1F1F1F")
)
```

`primary` drives highlights and active states, `secondary` drives chips and
bubbles. The `_dark` variants override dark mode and default to the light values.

Fonts are two CSS variables: `--font-display` for the agent's name, the names in
the agents dropdown and page titles, and `--font-sans` for everything else. Both default to the system font
stack, and `--font-display` follows `--font-sans` until you set it. Set them from
`.head()`, and serve the font files with `.copy_public()`:

```python theme={null}
web = (
    cycls.Web()
    .copy_public("./fonts/")
    .head("""<style>
      @font-face { font-family: "Brand"; src: url(/public/fonts/Brand.woff2); }
      :root { --font-display: "Brand", sans-serif; }
    </style>""")
)
```

## The empty-chat screen

> [tab] Suggestions
>
> ```python theme={null}
> web = cycls.Web().suggestions(True)
> ```
>
> Prompt starters, off by default.

> [tab] Example gallery
>
> ```python theme={null}
> web = cycls.Web().examples({
>     ("Data analysis", "تحليل البيانات"): [
>         "https://atlas.cycls.ai/shared/u_123/abc",
>     ],
>     "Landing pages": [
>         "https://atlas.cycls.ai/shared/u_123/def",
>         {"video": "/public/tour.mp4", "title": "Watch a two minute tour"},
>     ],
> })
> ```
>
> Each entry is either a share URL of a real conversation this agent produced,
> which renders as an artifact card with Use prompt and View, or a video, which
> renders as a tutorial card. A tuple key gives the category pill both locales.

> [tab] Explore menu
>
> ```python theme={null}
> web = cycls.Web().explore(
>     {"name": "Atlas", "url": "https://atlas.cycls.ai", "logo": "./atlas.svg"},
>     {"name": "Scout", "url": "https://scout.cycls.ai", "name_ar": "كشاف"},
> )
> ```
>
> The agents dropdown in the header. A static list overrides the CMS list. With
> neither, the menu is hidden.

## SEO and social

```python theme={null}
web = (
    cycls.Web()
    .seo(title="Atlas, the research agent", description="Ask anything about your documents.")
    .head('<meta name="google-site-verification" content="..." />')
)
```

`.seo()` covers the page title and meta description when they should differ from
the brand copy. `.head()` appends raw HTML to `<head>` and is repeatable.

Every agent also serves `/og.png`, a generated social preview, plus
`/robots.txt`, `/sitemap.xml` and `/llms.txt`.

## Mobile app

```python theme={null}
web = cycls.Web().mobile_app(
    ios="https://apps.apple.com/app/cycls/id6802279454",
    android="https://play.google.com/store/apps/details?id=com.cycls.app",
)
```

Points phone visitors to the Cycls app. Each link must be an `https://` store URL.
On iOS or Android, a bar under the header reads "Cycls App, For a better
experience" with an **Open** button to that platform's link. The bar names the
Cycls app and shows its icon, whatever your branding. Dismissing it or tapping
Open hides it for 14 days.

Each browser's own prompt comes first:

* An App Store link adds the `apple-itunes-app` meta tag, so Safari on iPhone and
  iPad shows Apple's banner instead of the bar.
* A Play link serves `/manifest.webmanifest`, so on Android, Open can bring up
  Chrome's install sheet.

## Static files

```python theme={null}
web = cycls.Web().copy_public("./assets/logo.png", "./downloads/")
```

Files keep their relative paths, so the logo is served at
`https://your-agent.cycls.ai/public/assets/logo.png`.

## Uploads

```python theme={null}
web = cycls.Web().max_upload(256)   # MB per file, default 512
```

Enforced server-side and pre-checked in the client so oversized files fail fast.

## Voice input

The mic in the composer records, and your server turns the recording into text
with a speech-to-text model. The browser sends audio and gets the words back. It
never learns which service or model heard them, and never holds a key.

`.voice()` names the model as `vendor/model`, the way `cycls.LLM` does, with the
service's `base_url`. Any service that speaks OpenAI's audio transcriptions API
works:

```python theme={null}
# OpenRouter: one key for every transcription model it carries
web = cycls.Web().voice("openrouter/elevenlabs/scribe-v2", base_url="https://openrouter.ai/api/v1",
                        api_key=os.environ["OPENROUTER_API_KEY"])

# An open Whisper model on Groq. Reads GROQ_API_KEY from the server's environment
web = cycls.Web().voice("groq/whisper-large-v3-turbo", base_url="https://api.groq.com/openai/v1")

# Your own server, such as vLLM serving Whisper or Voxtral
web = cycls.Web().voice("vllm/openai/whisper-large-v3", base_url="https://whisper.example.com/v1")

# No mic
web = cycls.Web().voice(False)
```

Without `.voice()`, the mic uses OpenAI's `gpt-4o-transcribe` whenever
`OPENAI_API_KEY` is set, and is hidden when it is not. Every vendor but OpenAI
needs a `base_url`. The key is `api_key`, or `<VENDOR>_API_KEY` from the server's
environment. Use `headers=` for an endpoint that authenticates another way, such
as a proxy.

Through OpenRouter, the same call reaches ElevenLabs, Deepgram, AssemblyAI and
Google models, and open ones such as Whisper, Voxtral and Nemotron. List them with
`GET https://openrouter.ai/api/v1/models?output_modalities=transcription`.

## Analytics and push

```python theme={null}
web = (
    cycls.Web()
    .analytics(cycls.PostHog(), cycls.GTM("GTM-ABCD123", events=["sign_up", "purchase"]))
    .notifications(cycls.OneSignal("00000000-0000-0000-0000-000000000000"))
    .affiliate(os.environ["REWARDFUL_KEY"])
)
```

`.analytics(True)` is shorthand for the PostHog default. Providers are plugins
over one canonical event pipe, and each can be scoped with an `events` allowlist
of the names below. `.notifications()` adds web push, where the permission card
is ours and the trigger is a platform decision.

PostHog identifies signed-in people with their name, email, organization and
plan. The plan is the token's `pla` claim, the same value as `context.user.plan`.
A `u:` plan sets `user_plan` and `user_is_paid`, and an `o:` plan sets `org_plan`
and `org_is_paid`, so switching between personal and an organization updates only
that pair. Paid means any plan except `u:free_user` and `o:free_org`.

> [!WARNING]
>
> Since 0.0.2.145, the `plan_name`, `plan_status`, `plan_amount`, `plan_period`,
> `plan_period_end`, `plan_canceled_at` and `is_paid` person properties are no
> longer set, and the `subscription_cancelled` and `subscription_resumed` events
> are gone. Move dashboards to the plan properties above.

> [accordion] Events
>
> | Events | When |
> | - | - |
> | `sign_up_start` | a visitor starts to sign up, once per visit |
> | `sign_up_attempted`, `sign_in_attempted` | a sign-up or sign-in form, or an OAuth button, is submitted |
> | `sign_up` | an account is created, once per account |
> | `first_agent_use` | the account's first chat |
> | `user_signed_out` | the person signs out |
> | `message_sent` | every send, with its `origin` |
> | `message_retried`, `message_regenerated`, `message_failed` | a retry, a regenerate, a send that failed |
> | `message_queued`, `queued_message_sent`, `queued_message_edited`, `queued_message_dropped` | a message written while the agent works. `queued_message_sent` carries `remaining`, how many still wait |
> | `turn_completed` | a run ends, once per run |
> | `run_failed` | a run ends `failed` or `interrupted`, once per run, with `status`, `reason`, `error_id` and `via` (`stream` or `poll`) |
> | `run_busy` | a send is refused because the chat already has a run |
> | `generation_stopped` | every Stop |
> | `prompt_restored` | a Stop before any of the reply showed puts the prompt back in the composer |
> | `context_compacted` | the loop compacts the chat's context |
> | `chat_loaded`, `chat_cleared`, `chat_renamed`, `chat_favorited`, `chat_deleted` | chat list actions |
> | `chat_title_generated` | a new chat named by the agent's model, with `source`, `length` and `language` |
> | `examples_shown`, `example_category_selected`, `example_prompt_used`, `example_viewed`, `example_watched` | the example gallery |
> | `suggestion_category_selected`, `suggestion_prompt_clicked` | prompt starters |
> | `artifact_completed`, `canvas_loader_shown` | the agent opens a file on the canvas, or the canvas opens on a file the agent is still writing |
> | `file_uploaded`, `file_upload_failed`, `file_saved`, `file_renamed`, `file_deleted`, `file_shared`, `folder_created` | file actions in the composer, Files and the canvas |
> | `trash_restored`, `trash_purged` | something comes back from the trash, or is deleted for good |
> | `app_updated` | an app is renamed or given a new icon |
> | `share_created`, `share_create_failed`, `share_deleted` | a chat is shared, sharing it fails, or a share link is revoked |
> | `share_viewed`, `share_view_failed` | a shared page loads, or fails to |
> | `share_cta_clicked` | Sign in, Go to or Try on a shared page's bar, with `signed_in` |
> | `share_fork_clicked`, `share_forked` | Continue this conversation, and the fork that follows |
> | `ui_action` | every minor agent `ui` event, with its `action` |
> | `ask_answered`, `ask_dismissed`, `followup_accepted` | the question card is answered or dismissed, or a follow-up chip is taken |
> | `confirm_approved`, `confirm_dismissed`, `connector_permissions_changed` | the approval card is approved or dismissed, or a tool's approval mode changes |
> | `connector_connect_clicked`, `connector_dismissed`, `connector_disconnected`, `connector_toggled`, `connector_directory_opened`, `connector_prompt_used`, `connector_mentioned` | connector actions |
> | `skill_uploaded`, `skill_written`, `skill_create_chat` | a skill is uploaded from the Skills tab or written in its form, or a chat to create one starts |
> | `ask_toggled`, `followups_toggled`, `web_search_toggled`, `approve_mode_changed` | a settings switch changes |
> | `notification_prompt_shown`, `notification_prompt_answered` | the push permission card |
> | `announcement_shown`, `announcement_clicked`, `announcement_dismissed` | a What's new modal or corner tip |
> | `app_banner_shown`, `app_banner_clicked`, `app_banner_dismissed` | the [mobile app](#mobile-app) bar, with `platform` |
> | `paywall_shown`, `limit_reached` | the agent opens the plans window. `limit_reached` fires on every refusal for a limit, and `paywall_shown` only when the window opens, once per period on each device |
> | `plan_modal_opened`, `plan_modal_closed`, `plan_manage_clicked` | the plans window, with `why` (`limit`) when a limit opened it and the close `method`, such as `not_now` |
> | `checkout_start`, `purchase` | checkout starts, with `why` (`limit` or `menu`), or a paid checkout completes |
> | `mic_started`, `mic_stopped`, `mic_cancelled`, `mic_transcribed`, `mic_transcription_failed`, `mic_permission_denied` | voice input |
> | `client_crashed` | the client catches a render error |
> | `settings_opened`, `theme_changed`, `language_changed`, `explore_opened`, `explore_agent_clicked`, `source_opened` | Settings opens, the theme or language changes, the agents menu is used, or a source is opened |

## Reacting to finished runs

```python theme={null}
async def on_run(record):
    if record["status"] == "failed":
        await page_oncall(record)


web = cycls.Web().on_run(on_run)
```

Called once when a run reaches any terminal status: done, stopped, interrupted or
failed. Use it for push, email, a webhook or a row in a table. Exceptions are
logged and never reach the run.

| Field | Value |
| - | - |
| `run` | the run's id |
| `chat_id` | the chat it ran in |
| `user` | the user's id |
| `status` | `done`, `stopped`, `interrupted` or `failed` |
| `reason` | why it did not finish: `stopped`, `budget` (the 45-minute cap), `error`, `disconnected` or `shutdown`. `None` when `done` |
| `started` | when it began, ISO 8601 |
| `heartbeat` | the record's last write, ISO 8601, which is when it ended |
| `ms` | how long it ran, in milliseconds |
| `owner` | the container that ran it |
| `error_id` | on a crash, the reference the user was shown, also on the `level=error` log record |
| `taken_back` | `"1"` when Stop took the prompt back |

`error_id` and `taken_back` are present only when they apply.

## Method reference

| Method | Purpose |
| - | - |
| `.auth(provider)` | [`cycls.Clerk()`](https://docs.cycls.com/web/auth) or `cycls.JWT(...)` |
| `.iap(config)` | [Apple in-app purchase](https://docs.cycls.com/web/monetization.md#apple-in-app-purchase) entitlements |
| `.title(str)` | tab and app title |
| `.brand(locale, ...)` | static branding per locale |
| `.cms(brand=, explore=, connectors=, token=)` | pull copy from a CMS |
| `.theme(name)` | `"default"` or `"dev"` |
| `.colors(...)` | accent colors, light and dark |
| `.seo(title=, description=)` | page and social copy |
| `.head(html)` | append to `<head>`, repeatable |
| `.explore(*agents)` | the agents dropdown |
| `.examples(shares)` | the example gallery |
| `.suggestions(bool)` | prompt starters |
| `.analytics(*providers)` | PostHog, GTM, or `True` for the default |
| `.notifications(*providers)` | web push plugins |
| `.affiliate(key)` | referral tracking |
| `.mobile_app(ios=, android=)` | point phone visitors to the Cycls app |
| `.plans(pay=, currency=, words=)` | [the plans window](https://docs.cycls.com/web/monetization.md#the-plans-window): payment marks, a local currency, plan words |
| `.voice(model, base_url=, api_key=, headers=)` | [voice input](#voice-input): the model that turns the mic's recordings into text, or `False` |
| `.max_upload(mb)` | per-file upload cap |
| `.copy_public(*files)` | files served at `/public` |
| `.workspaces(create=)` | [multi-workspace mode](https://docs.cycls.com/web/workspaces.md) |
| `.connectors(*objs)` | [connector directory](https://docs.cycls.com/agents/connectors.md) |
| `.on_run(fn)` | callback when a run ends |

## Next

> [card] [Authentication](https://docs.cycls.com/web/auth.md)
>
> Clerk, any OIDC provider, and what lands in `context.user`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.