Deploy

Publish a function, app or agent to a URL, set its size and limits, and understand what survives a redeploy.

This page is for developers taking a working local file to production.

Prerequisites: a CYCLS_API_KEY from Cycls Cloud, set in the environment or in a .env file beside your code.

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

Naming

The deployment name is the decorator’s name= or the function name, and it becomes the subdomain:

@cycls.agent(name="atlas", web=web, volumes={"/workspace": chats})
async def my_agent(context): ...
# https://atlas.cycls.ai

Redeploying the same name updates it in place. Names are checked for availability before the archive uploads, and the error names the conflict.

To pick one target out of a file with several decorated objects:

cycls deploy file.py::atlas

What deploy produces

Deploy reads the shape of the decorated function:

Shape	Result
@cycls.agent	a chat product at https://<name>.cycls.ai
@cycls.app	an ASGI service at https://<name>.cycls.ai
@cycls.function taking port	a server at https://<name>.cycls.ai
@cycls.function with no port	a named endpoint, called with cycls.remote("<name>")

Sizing and limits

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

Argument	Accepted values	Default	Notes
cpu	1, 2, 4, 6, 8	platform choice	raised automatically if memory requires more
memory	512Mi to 32Gi	1Gi
timeout	seconds, up to 3600	1200	how long one request may run
concurrency	integer	high	requests one instance serves at once. Set to 1 for compute
volumes	mount path to volume	none	required at /workspace for agents
schedule	cycls.Cron(...)	none	bare functions only

Instances scale to zero when idle, so an unused deployment costs nothing and the next call pays a cold start of a few seconds.

Environment variables

Values reach the container two ways.

1. Bundle a dotenv file with the image. The SDK loads .env automatically at import.

   image = cycls.Image().copy(".providers.env", ".env")
   

2. Read os.environ inside the function body for values the platform injects, such as CYCLS_VOLUMES.

Keep CYCLS_API_KEY out of the image. It is a deploy credential, not a runtime one. See Environment variables for the full list.

Calling a deployed endpoint

import cycls

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

Authentication is a token derived as sha256(api_key : name), computed independently by the deployer and the caller and stored nowhere. Any machine holding your CYCLS_API_KEY can call your deployments, and nothing else can.

Rotating the key strands existing services, because their baked token came from the old key. Remove and redeploy them after a rotation.

Every call carries its Python and cloudpickle versions. The endpoint refuses a pickle that cannot cross the boundary and returns an explicit error instead of a confusing unpickle failure. Redeploy from the calling environment to resolve it.

Isolation boundary

Deployments under one account share a trust domain. Code running in one can reach another’s workspace storage. For hard isolation, such as production against experiments or separating clients, deploy from a separate organization. Each organization is its own tenant with its own boundary.

Removing a deployment

cycls rm notes          # asks for confirmation
cycls rm notes -y       # skips it

cycls rm deletes the deployment and detaches its volumes. Volume data is not touched, and redeploying the same name reattaches it with files intact. Deleting data is always explicit:

cycls volume delete notes-data

Deploying from Python

my_agent.deploy()
my_app.deploy()
simulate.deploy()

Keep these out of module scope. Every command imports your file, so a top-level deploy() fires during cycls shell and cycls deploy too.

if __name__ == "__main__":
    my_agent.deploy()

Next

Observability

Logs, error references, cost and SQL over both.