Functions

@cycls.function is the bottom layer. It takes a Python function, packages it with the dependencies you declare, and runs it wherever you point it.

simulate.py

import cycls


@cycls.function(image=cycls.Image().pip("numpy"))
def simulate(n=1_000_000):
    import numpy as np
    pts = np.random.rand(int(n), 2)
    return float(4 * ((pts ** 2).sum(axis=1) <= 1).mean())

Three verbs decide where it runs:

simulate.run(1000)        # your Docker
simulate.remote(1000)     # Cycls Cloud, the code you are holding
simulate.deploy()         # Cycls Cloud, frozen and callable by name

How the code gets there

The function is serialized with cloudpickle, bytecode, closures and captured variables included, then executed inside a container built from your Image. The same pickle runs locally and in the cloud, so what you tested is what ships. Two version rules keep that safe, 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.

Functions defined in the file you deploy travel by value. Functions imported from another module travel by reference, so the container needs that module. Bundle it with cycls.Image().copy("helpers.py"), and anything copied lands in /app, which is on sys.path.

Running locally

result = simulate.run(1000)

The image is built or reused, the function executes, and the return value comes back. Print statements stream to your terminal while it runs. To look around inside the exact environment the function sees:

cycls shell simulate.py
# Entering cycls/simulate:730f149a (exit to leave)
root@a1b2c3:/app#

The development loop

cycls run simulate.py                # rerun on every save, local Docker
cycls run simulate.py --remote       # rerun on every save, in the cloud
cycls run simulate.py --n 1000       # arguments bind to the signature

Trailing --name value arguments bind to the function’s parameters. Annotated parameters convert through their annotation, so n: int gets an int. Unannotated ones are parsed as Python literals, so --data "[1,2]" becomes a list. Anything else stays a string. A save during a run queues the next run instead of killing the current one. For anything with several calls, a fan-out, or a mix of local and remote, mark a driver:

@cycls.local_entrypoint
def main(n: int = 1_000_000):
    print(simulate.remote(n))
    print(simulate.map([10, 20, 30]))

The entrypoint runs on your machine on every save, and the verbs inside it decide where the work happens. Keep driver calls inside it. A top-level simulate.remote(...) fires on every import, including during cycls deploy.

Running in the cloud with current code

simulate.remote(1_000_000)          # one call
simulate.map([10**6] * 100)         # one call per item, ordered results

remote() ships the live bytecode to an executor, which is a small service provisioned once per image and shared by every function using that image. The first call for a given image takes about ninety seconds while it provisions. After that, a call costs network plus compute. Edit the function, call again, and the new code runs. There is no redeploy step. map() fans one call per item across autoscaled instances and returns results in input order. It raises on the first failure, so return errors as data when you want per-item tolerance:

@cycls.function(image=cycls.Image().pip("httpx", "beautifulsoup4"))
def scrape(url):
    try:
        ...
    except Exception as e:
        return {"url": url, "error": str(e)}

Deploying

cycls deploy simulate.py
# Deployed: https://simulate.cycls.ai
# Call it: cycls.remote("simulate")(...)

Deploy reads the function’s shape. A function that takes a port parameter is a server and gets its own URL. A bare function becomes a named endpoint, frozen at deploy time and callable from any machine that has your API key:

import cycls

pi = cycls.remote("simulate")(10_000_000)
results = cycls.remote("simulate").map([10**6] * 100)

The difference matters. f.remote() runs your current code, which is what you want while developing. cycls.remote("name") calls what was deployed, which is what a caller without your source needs.

Serving instead of returning

Any function that binds a port is a server:

@cycls.function(image=cycls.Image().pip("fastapi", "uvicorn"))
def api(port):
    from fastapi import FastAPI
    import uvicorn

    app = FastAPI()

    @app.get("/")
    async def root():
        return {"ok": True}

    uvicorn.run(app, host="0.0.0.0", port=port)

cycls run api.py        # http://localhost:8080
cycls deploy api.py     # https://api.cycls.ai

For a service with auth and per-user storage, use @cycls.app, which is this pattern with the plumbing already done.

Sizing and limits

@cycls.function(
    image=cycls.Image().pip("torch"),
    cpu=4,
    memory="8Gi",
    timeout=1800,
    concurrency=1,
)
def train(epochs): ...

Argument	Meaning
`cpu`	1, 2, 4, 6 or 8
`memory`	`"512Mi"` through `"32Gi"`
`timeout`	seconds a single request may run, up to 3600
`concurrency`	requests one instance serves at once. Set it to 1 for compute
`volumes`	mount paths to volumes
`schedule`	a cron that fires the deployment
`python_version`	pin the container’s Python, must match your host

Keeping state warm

The process lives across calls on an instance, so expensive setup can be paid once per instance using a mutable default:

@cycls.function(image=cycls.Image().pip("fastembed"))
def embed(texts, _model={}):
    if "m" not in _model:
        from fastembed import TextEmbedding
        _model["m"] = TextEmbedding("BAAI/bge-small-en-v1.5")
    return [v.tolist() for v in _model["m"].embed(list(texts))]

First call loads the model, every call after is warm. That is a self-hosted embedding API in ten lines.

Method reference

Method	Meaning
`.run(args, *kwargs)`	execute in local Docker, `port=` serves
`.remote(args, *kwargs)`	execute current code in the cloud
`.map(items, workers=16)`	fan current code across instances, ordered
`.watch(args, *kwargs)`	run with file watching
`.build()`	build the image without running
`.deploy()`	freeze and publish
`cycls.remote(name)`	a callable for a deployed endpoint, `.map` included

Images

Declare packages, system libraries and bundled files.

Get started

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Functions

How the code gets there

Running locally

The development loop

Running in the cloud with current code

Deploying

Serving instead of returning

Sizing and limits

Keeping state warm

Method reference

Next

Images

​How the code gets there

​Running locally

​The development loop

​Running in the cloud with current code

​Deploying

​Serving instead of returning

​Sizing and limits

​Keeping state warm

​Method reference

​Next

Images

How the code gets there

Running locally

The development loop

Running in the cloud with current code

Deploying

Serving instead of returning

Sizing and limits

Keeping state warm

Method reference

Next