Quickstart

Before you start

Python 3.10 or newer
Docker running, for local runs and builds
A Cycls API key for deploying
A model key, for example ANTHROPIC_API_KEY or OPENAI_API_KEY

What the five minutes below look like: one file, one command, a live URL.

Install the SDK

pip install cycls

Check it:

cycls version

Set your keys

Cycls reads a .env file from the working directory automatically.

.env

CYCLS_API_KEY=your_cycls_key
ANTHROPIC_API_KEY=sk-ant-your_key

Keep two files. .env holds keys that stay on your machine, such as CYCLS_API_KEY. .providers.env holds keys the container needs, such as ANTHROPIC_API_KEY. Ship only the second one with cycls.Image().copy(".providers.env", ".env").

Scaffold an agent

cycls init my_agent

This writes my_agent.py:

my_agent.py

import cycls

image = cycls.Image()

chats = cycls.Volume("my-agent-chats")

web = (
    cycls.Web()
    .auth(cycls.Clerk())
    .title("my_agent")
)

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a helpful assistant.")
)


@cycls.agent(image=image, web=web, volumes={"/workspace": chats})
async def my_agent(context):
    async for ev in llm.run(context=context):
        yield ev

Four declarations and one function body. The image describes the container, the volume holds chat state, web configures the interface, and llm configures the model. The body receives a context and yields events.

Run it locally

cycls run my_agent.py

Cycls builds the image, starts the container and serves on http://localhost:8080. Every save rebuilds and reloads. The first build takes a minute or two, later ones are cached.

Deploy it

cycls deploy my_agent.py
#   [BUILDING]  ...
#   [DEPLOYING] ...
#   [DONE]      https://my-agent.cycls.ai

The build happens in the cloud, not on your laptop. The deployment name comes from the function name, and redeploying the same name updates it in place.

Give it tools

The managed loop ships with built-in tools. Enabling one is a single call, and each tool brings its own prompt guidance.

llm = (
    cycls.LLM()
    .model("anthropic/claude-sonnet-4-6")
    .system("You are a research assistant. Show your work.")
    .allowed_tools(["Bash", "Editor", "WebSearch", "Canvas"])
)

Now the agent can search the web, write files into the user’s workspace, run shell commands in a sandbox, and open results on the canvas. See Tools for the full set.

Talk to it over HTTP

Every agent serves an OpenAI-compatible endpoint, so existing clients work without changes.

curl https://my-agent.cycls.ai/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}], "stream": true}'

from openai import OpenAI

client = OpenAI(base_url="https://my-agent.cycls.ai", api_key="unused")

stream = client.chat.completions.create(
    model="my-agent",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Next steps

Core concepts

Run, remote and deploy, and when to use each layer.

Build an agent

The loop, the context object, and what the body yields.

Local and remote builds

What happens on your machine and what happens in the cloud.

Guides

End-to-end examples you can copy.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Give it tools

Talk to it over HTTP

Next steps

Core concepts

Build an agent

Local and remote builds

Guides

​Give it tools

​Talk to it over HTTP

​Next steps

Core concepts

Build an agent

Local and remote builds

Guides

Give it tools

Talk to it over HTTP

Next steps