> ## 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.
# Introduction
> Cycls is the deep-stack AI SDK for Python. Runtime, interface, intelligence and state are composable primitives in one file, deployed with one command.
Write the agent, the container it runs in, the interface it serves and the
storage it keeps, in one Python file. Then ship it.
```python hello.py theme={null}
import cycls
llm = (
cycls.LLM()
.model("anthropic/claude-sonnet-4-6")
.system("You are a helpful assistant.")
.allowed_tools(["Bash", "Editor", "WebSearch"])
)
@cycls.agent(volumes={"/workspace": cycls.Volume("hello-chats")})
async def hello(context):
async for ev in llm.run(context=context):
yield ev
```
```bash theme={null}
cycls deploy hello.py
# https://hello.cycls.ai
```
That deploy produces a chat interface, sign-in, per-user file storage, chat
history, share links, an OpenAI-compatible API endpoint and a sandboxed tool
loop. There is no Dockerfile, no YAML and no separate infrastructure repository.
## The four layers
| Layer | Primitive | What you declare |
| ------------ | -------------------------------- | ------------------------------------------------------------ |
| Runtime | [`cycls.Image`](/build/images) | pip packages, system packages, bundled files, build commands |
| Interface | [`cycls.Web`](/web/interface) | branding, auth, themes, analytics, workspaces |
| Intelligence | [`cycls.LLM`](/agents/models) | model, system prompt, tools, budgets, reasoning |
| State | [`cycls.Volume`](/build/volumes) | named persistent storage, attached by mount path |
Each primitive is an immutable builder, so every method returns a new object and
one base configuration can be branched without side effects.
## Three decorators
Decorators accept exactly the primitives they need. Each one extends the layer
below it, so anything a function can do, an app can do, and anything an app can
do, an agent can do.
```
@cycls.agent chat product, managed LLM loop, web UI
extends
@cycls.app blocking ASGI service, auth, per-user storage
extends
@cycls.function containerized Python, volumes, schedules
```
Run Python in a container locally, in the cloud, or on a schedule. Freeze it
as a named endpoint anyone with your key can call.
Return a FastAPI application and get a URL, sign-in and per-user storage.
A chat product with a managed model loop, tools, memory, files and a web
interface.
## What an agent includes
Streaming chat in light and dark, English and Arabic, a file canvas, voice
input, share links and generated social previews.
Tool calling, retries, context compaction, cost accounting, and background
runs that survive a dropped connection.
Sandboxed bash, file editing, web search, a real browser, a key-value store,
a canvas, app building, and your own Python handlers.
Per-user files and chats on a volume you own, team workspaces, trash and
restore, and shareable conversations.
Clerk out of the box or any OIDC provider. Organizations, roles, plans and
feature flags arrive as `context.user`.
OAuth and API-key grants a user makes once, with per-tool approvals, an audit
trail, and remote MCP servers on any provider.
## Model support
One builder covers Anthropic natively and every OpenAI-compatible endpoint
through a base URL.
```python theme={null}
cycls.LLM().model("anthropic/claude-sonnet-4-6")
cycls.LLM().model("openai/gpt-5.4")
cycls.LLM().model("groq/llama-3.3-70b").base_url("https://api.groq.com/openai/v1")
cycls.LLM().model("local/qwen3").base_url("http://localhost:8000/v1")
```
Reasoning control, tool calls and streaming are unified across providers. See
[Models](/agents/models).
## Start here
Install, run locally, deploy. About five minutes.
Layers, builders, and the difference between run, remote and deploy.
A guided build with tools, branding and a quota check.
Every command, flag and default.