# Cycls

> The deep-stack AI SDK for Python. Runtime, interface, intelligence and state as composable primitives, in one file, deployed with one command.

- [Introduction](https://docs.cycls.com/get-started/introduction.md): Cycls is the deep-stack AI SDK for Python. Runtime, interface, intelligence and state are composable primitives in one file, deployed with one command.
- [Quickstart](https://docs.cycls.com/get-started/quickstart.md): Install Cycls, run an agent on your machine, then deploy it to a public URL.
- [Core concepts](https://docs.cycls.com/get-started/concepts.md): The mental model behind Cycls: three layers, four builders, and three verbs.
- [Functions](https://docs.cycls.com/build/functions.md): Turn any Python function into a container that runs on your laptop, in the cloud, or on a schedule, without writing a Dockerfile.
- [Images](https://docs.cycls.com/build/images.md): Declare pip packages, system libraries, bundled files and build commands in Python. Cycls hashes the result into a cached Docker image.
- [Volumes](https://docs.cycls.com/build/volumes.md): Named persistent storage you attach to any deployment at any mount path. Data outlives the deployments that use it.
- [Cron](https://docs.cycls.com/build/cron.md): Add one argument to a function and the platform calls it on a schedule. No scheduler to run, nothing to drift.
- [Apps](https://docs.cycls.com/build/apps.md): Return a FastAPI application and get a URL, sign-in, and per-user storage. Everything a function can do, an app can do too.
- [Agents](https://docs.cycls.com/agents/overview.md): A chat product in one decorator: managed LLM loop, tools, files, history and a web interface.
- [Models](https://docs.cycls.com/agents/models.md): One builder for every provider: Anthropic natively, and any OpenAI-compatible endpoint through a base URL.
- [Tools](https://docs.cycls.com/agents/tools.md): Enable built-in tools by name, or register your own Python handlers. Both stream into the same UI.
- [Streaming components](https://docs.cycls.com/agents/streaming.md): Yield strings for markdown or dicts for rich components: thinking bubbles, tables, code, callouts, images and client actions.
- [Context](https://docs.cycls.com/agents/context.md): Every turn hands your agent a context object with the conversation, the user, the workspace and the switches that user set.
- [Instructions and skills](https://docs.cycls.com/agents/knowledge.md): Give an agent standing instructions it reads every turn, and skill packs it loads only when the task calls for them.
- [Files and the canvas](https://docs.cycls.com/agents/files.md): Every user gets a workspace of files. The canvas renders spreadsheets, documents, slides, PDFs, images and HTML without leaving the chat.
- [Connectors and MCP](https://docs.cycls.com/agents/connectors.md): A user connects an account once, and the tools that need it get a live credential. OAuth, pasted keys, private endpoints and remote MCP servers.
- [Sandbox and trust model](https://docs.cycls.com/agents/sandbox.md): What isolates the bash tool from your secrets, what that isolation covers, what it does not, and the settings that close the remaining gaps.
- [Custom loops](https://docs.cycls.com/agents/custom-loop.md): Hook the default loop with a few lines, or replace it entirely and keep the session, provider, tools and compaction.
- [Interface](https://docs.cycls.com/web/interface.md): Branding, themes, colors, SEO and the empty-chat screen. Configure the chat product your agent ships with.
- [Authentication](https://docs.cycls.com/web/auth.md): Sign-in is a provider object. Clerk works out of the box, and any OIDC issuer works with a JWKS URL.
- [Workspaces](https://docs.cycls.com/web/workspaces.md): Give every user a private workspace and let teams share one, with role-based access and full isolation of files, chats and skills.
- [Plans and quotas](https://docs.cycls.com/web/monetization.md): Read the subscription tier from context.user.plan, meter usage on the workspace volume, and verify Apple in-app purchases offline.
- [Local and remote builds](https://docs.cycls.com/ship/builds.md): Cycls builds a container three ways: on your Docker, on a shared cloud executor, and on the deploy service. Know which one runs and what it contains.
- [Deploy](https://docs.cycls.com/ship/deploy.md): Publish a function, app or agent to a URL, set its size and limits, and understand what survives a redeploy.
- [Logs, cost and SQL](https://docs.cycls.com/ship/observability.md): Find a user's failed request by its reference id, aggregate model spend, and run SQL across logs and billing.
- [CLI reference](https://docs.cycls.com/ship/cli.md): Every cycls command with its arguments, flags, defaults and output: run, deploy, shell, ls, rm, logs, cost, sql, volume, init, version.
- [Build your first agent](https://docs.cycls.com/guides/first-agent.md): A guided build from an empty directory to a deployed agent with tools, a system prompt, branding and a quota check.
- [Add a custom tool](https://docs.cycls.com/guides/custom-tool.md): Define a JSON schema, write an async handler, and register it with .on(). The return value reaches both the user and the model.
- [Serve a FastAPI app](https://docs.cycls.com/guides/fastapi-app.md): Deploy an ASGI service with sign-in, per-user storage and a bundled front end, using @cycls.app.
- [Run batch jobs](https://docs.cycls.com/guides/batch-jobs.md): Fan work across autoscaled instances with map, keep expensive setup warm, and call the result from anywhere with your API key.
- [Build a data warehouse on a volume](https://docs.cycls.com/guides/duckdb-warehouse.md): Store Parquet on a Cycls volume, query it with DuckDB from a function, schedule the ingest, and let an agent ask questions in SQL.
- [Schedule a nightly report](https://docs.cycls.com/guides/scheduled-reports.md): Run a function on a cron, write the output to a volume, and let an agent hand it to users.
- [Open and self-hosted models](https://docs.cycls.com/guides/self-hosted-models.md): Point an agent at DeepSeek, Kimi, GLM or your own vLLM and SGLang servers, including endpoints behind proxy authentication.
- [Python API](https://docs.cycls.com/reference/python.md): Every name exported by the cycls package, with its purpose and the page that documents it.
- [Agent HTTP API](https://docs.cycls.com/reference/agent-api.md): Every endpoint a deployed Cycls agent serves: chat, OpenAI compatibility, chats, files, share links, workspaces, connectors and tool settings.
- [Environment variables](https://docs.cycls.com/reference/environment.md): Every variable the Cycls SDK, the agent runtime and its optional services read, with where each one belongs.
- [Limits](https://docs.cycls.com/reference/limits.md): Sizes, timeouts, caps and retention windows across builds, deployments, storage, uploads and the agent loop.
- [Examples](https://docs.cycls.com/resources/examples.md): Runnable examples for every primitive: functions, a DuckDB warehouse on a volume, ASGI apps, and agents from minimal to production shaped.
- [FAQ](https://docs.cycls.com/resources/faq.md): Answers to common questions about Docker requirements, model support, storage, pricing boundaries and how Cycls compares to other frameworks.
- [Contributing](https://docs.cycls.com/resources/contributing.md): Set up the SDK repository, run the three test tiers, and open a pull request.
- [llms.txt](https://docs.cycls.com/llms.md): A machine-readable index of this documentation, for AI tools and agents that retrieve Cycls docs.
- [llms-full.txt](https://docs.cycls.com/llms-full.md): The full text of this documentation in one file, for AI tools and agents that need the complete corpus.
- [Cloud API](https://docs.cycls.com/api-reference/introduction.md): The REST API behind the CLI: deploy services, manage volumes, read logs and run SQL. Authenticate with an API key or a bearer token.
- [Check Name Availability](https://docs.cycls.com/api-reference/deployments/check-name-availability.md): Check if a deployment name is available for the authenticated user. Returns whether the name can be used and a reason if not.
- [Deploy](https://docs.cycls.com/api-reference/deployments/deploy.md): Deploy a service. Returns NDJSON stream with progress updates.
- [List Service](https://docs.cycls.com/api-reference/deployments/list-service.md): Lists all services for the authenticated user or organization.
- [Delete a Service](https://docs.cycls.com/api-reference/deployments/delete-a-service.md)
- [Create a Volume](https://docs.cycls.com/api-reference/volumes/create-a-volume.md): Explicitly create a volume (idempotent). Deploys referencing an unknown volume also create it; content operations never do.
- [List Volumes](https://docs.cycls.com/api-reference/volumes/list-volumes.md): Volumes with the deployments currently mounting them, read live from the service templates, the sole store of attachments.
- [Delete a Volume](https://docs.cycls.com/api-reference/volumes/delete-a-volume.md): Refuses while any deployment mounts it. Bucket deletion is backstopped by GCS soft delete.
- [Get a Signed Upload URL for a Volume Object](https://docs.cycls.com/api-reference/volumes/get-a-signed-upload-url-for-a-volume-object.md): Strict: the volume must already exist, uploads never create one.
- [Get a Signed Download URL for a Volume Object](https://docs.cycls.com/api-reference/volumes/get-a-signed-download-url-for-a-volume-object.md)
- [List Objects in a Volume](https://docs.cycls.com/api-reference/volumes/list-objects-in-a-volume.md)
- [Delete an Object from a Volume](https://docs.cycls.com/api-reference/volumes/delete-an-object-from-a-volume.md)
- [Get Service Logs](https://docs.cycls.com/api-reference/logs/get-service-logs.md): Fetch logs from Cloud Logging for a specific service. Use `cursor` from response as `since` to poll for new logs.
- [SQL over your logs and billing](https://docs.cycls.com/api-reference/logs/sql-over-your-logs-and-billing.md): Run SQL against your own logs and billing data. Two views are pre-set in your default dataset:
- [Get User Subscription](https://docs.cycls.com/api-reference/billing/get-user-subscription.md): Fetches the billing subscription details for the authenticated user from Clerk.
- [Changelog](https://docs.cycls.com/changelog.md): Releases of the Cycls SDK, newest first. Versions match the published packages on PyPI.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


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