Interface

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

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)
)

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

Branding

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

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

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():

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

Suggestions
Example gallery
Explore menu

web = cycls.Web().suggestions(True)

Prompt starters, off by default.

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.

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.

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

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

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

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:

# 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

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.

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.

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

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()` or `cycls.JWT(...)`
`.iap(config)`	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: payment marks, a local currency, plan words
`.voice(model, base_url=, api_key=, headers=)`	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
`.connectors(*objs)`	connector directory
`.on_run(fn)`	callback when a run ends

Authentication

Clerk, any OIDC provider, and what lands in context.user.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Branding

Pulling copy from a CMS

Theme and colors

The empty-chat screen

Mobile app

Static files

Uploads

Voice input

Analytics and push

Reacting to finished runs

Method reference

Next

Authentication

​Branding

​Pulling copy from a CMS

​Theme and colors

​The empty-chat screen

​SEO and social

​Mobile app

​Static files

​Uploads

​Voice input

​Analytics and push

​Reacting to finished runs

​Method reference

​Next

Authentication

Branding

Pulling copy from a CMS

Theme and colors

The empty-chat screen

SEO and social

Mobile app

Static files

Uploads

Voice input

Analytics and push

Reacting to finished runs

Method reference

Next