Core concepts

The mental model behind Cycls: three layers, four builders, and three verbs.

Four ideas carry most of the SDK. Read them in order and the rest of the reference makes sense on first pass.

1. Three layers

Each layer extends the one below it, so anything a Function can do an App can do, and anything an App can do an Agent can do.

Layer	Input	Output	Use it for
Function	function arguments	return value	batch jobs, APIs, scheduled work, heavy compute
App	HTTP requests	an ASGI app you return	dashboards, internal tools, custom front ends
Agent	context	a stream of events you yield	chat products

2. Four builders

Configuration lives in fluent, immutable builders. Every method returns a new object, so one base config can be branched safely.

base = cycls.Image().pip("httpx")

fast = base.pip("orjson")        # a new Image
slow = base.apt("ffmpeg")        # another new Image, `base` is unchanged

cycls.Image

.pip() .apt() .copy() .run() .rebuild()

cycls.Web

.auth() .title() .brand() .analytics() .workspaces()

cycls.LLM

.model() .system() .tools() .allowed_tools() .price()

cycls.Volume

.read_only() .sub_path()

Decorators accept exactly the builders they need, never loose keyword soup.

@cycls.function(image=..., volumes=..., schedule=..., cpu=..., memory=...)
@cycls.app(image=..., volumes=..., auth=...)
@cycls.agent(image=..., web=..., volumes=...)

3. Three verbs

The same three words work in Python and on the command line.

Verb	Where the code runs	Which code runs
run	your Docker	the code you are holding
remote	Cycls Cloud	the code you are holding
deploy	Cycls Cloud	the code frozen at deploy time

simulate.run(1000)        # local Docker
simulate.remote(1000)     # cloud, current code
simulate.deploy()         # cloud, frozen and named

cycls run file.py            # local Docker, rerun on save
cycls run file.py --remote   # cloud, rerun on save
cycls deploy file.py         # freeze and publish

f.remote() is the development loop. cycls.remote("name") calls what was deployed, from any machine that has your API key. Read Local and remote builds for what happens in each case.

4. Code travels as a pickle

Your function is serialized with cloudpickle, including closures and captured variables, then executed inside a container built from your Image. Two rules follow, and both are enforced for you:

• The container’s Python matches your host’s major and minor version.
• The container’s cloudpickle matches your host’s exact version.

A function defined in the file you deploy travels by value. A function imported from another module travels by reference, so the container will try to import that module. If you split code across files, bundle them with cycls.Image().copy("helpers.py") so the import resolves.

State lives on volumes

Containers are stateless. Anything that must survive a redeploy goes on a volume, which is named storage attached at a mount path.

data = cycls.Volume("training-data")

@cycls.function(volumes={"/data": data})
def crunch(day):
    import pandas as pd
    return pd.read_parquet(f"/data/events-{day}.parquet").sum()

Agents keep chats, files and credentials under /workspace, so the decorator requires a volume there:

@cycls.agent(volumes={"/workspace": cycls.Volume("my-agent")})
async def my_agent(context):
    ...

Deleting a deployment detaches its volumes and never deletes their data.

Images are content addressed

Cycls hashes the image declaration, including the contents of copied files, into a deterministic Docker tag. Identical inputs reuse the cached build everywhere. Change one package and only that layer rebuilds.

Next steps

Agents

The managed loop, the context object and the event stream.

Functions

Run, remote, map, deploy and schedule.