Apps

@cycls.app is a function that returns an ASGI application. Cycls serves it, gives it a URL, and wires in identity and storage.

notes.py

import cycls


@cycls.app(auth=cycls.Clerk(), volumes={"/workspace": cycls.Volume("notes")})
def notes():
    from fastapi import FastAPI

    app = FastAPI()

    @app.get("/me")
    async def me(user=notes.auth):
        return {"id": user.id, "plan": user.plan}

    @app.post("/notes")
    async def create(body: dict, ws=notes.workspace):
        db = cycls.DB(ws)
        await db.put(f"docs/{body['id']}", body)
        return body

    return app

cycls run notes.py             # localhost:8080, reload on save
cycls run notes.py --remote    # https://dev-notes.cycls.ai, hot swap on save
cycls deploy notes.py          # https://notes.cycls.ai

The decorator

@cycls.app(name=None, image=None, volumes=None, auth=None, memory="1Gi")

Argument	Meaning
`name`	deployment name and subdomain, defaults to the function name
`image`	`cycls.Image` for packages and bundled files
`volumes`	mount paths to volumes
`auth`	`cycls.Clerk()` or `cycls.JWT(...)`, see Authentication
`memory`	container memory

The body runs inside the container at startup. Import heavy dependencies there, not at module level, so your local process stays light.

Identity

With auth= set, two dependencies become available on the decorated object.

@app.get("/me")
async def me(user=notes.auth):          # authenticated User, or 401
    return user


@app.get("/files")
async def files(ws=notes.workspace):    # that user's storage scope
    return [p.name for p in ws.root.iterdir()]

user carries id, org_id, org_slug, org_role, org_permissions, plan and features. See Authentication for providers and claims.

Storage

notes.workspace resolves a per-user scope on the volume mounted at /workspace. Two things live there:

Key-value
Files

@app.post("/notes")
async def create(body: NoteIn, ws=notes.workspace):
    db = cycls.DB(ws)
    await db.put(f"docs/{uuid4().hex[:12]}", body.dict())
    return {"ok": True}


@app.get("/notes")
async def list_notes(ws=notes.workspace):
    return [d async for _, d in cycls.DB(ws).items(prefix="docs/")]

Atomic per key, prefix scans, JSON values. Backed by the volume, so it survives redeploys.

@app.get("/report")
async def report(ws=notes.workspace):
    path = ws.root / "report.csv"
    return path.read_text()

ws.root is a Path scoped to that user. Write files there and they persist exactly like any other volume content.

Both need a volume at /workspace. Without one the error arrives on first use, not at deploy, so declare it whenever the app touches storage.

Serving a front end

Bundle the HTML with the image and return it from a route.

from pathlib import Path

HTML = str(Path(__file__).parent / "index.html")


@cycls.app(image=cycls.Image().copy(HTML, "index.html"), auth=cycls.Clerk())
def dashboard():
    from fastapi import FastAPI
    from fastapi.responses import HTMLResponse

    app = FastAPI()

    @app.get("/")
    async def index():
        pk = dashboard._auth_provider.resolve(dashboard.prod).get("pk", "")
        return HTMLResponse(Path("index.html").read_text().replace("__CLERK_PK__", pk))

    return app

The publishable key is resolved at request time, so the same file works locally and in production without a build step.

Running untrusted commands

cycls.Sandbox is a fluent wrapper around bubblewrap for executing commands with a read-only root, a cleared environment and no network unless you ask.

sandbox = (
    cycls.Sandbox()
    .setenv(PATH="/usr/local/bin:/usr/bin:/bin")
    .network(False)
    .timeout(120)
)


@app.post("/run")
async def run(cmd: str, ws=terminal.workspace):
    result = await sandbox.bind(str(ws.root), "/workspace").chdir("/workspace").run(
        ["bash", "-lc", cmd], env={"PATH": "/usr/bin:/bin"}
    )
    return {"output": result.output, "code": result.code}

Every method returns a new sandbox, so a shared base is safe to extend per request.

Method	Effect
`.bind(src, dst=None)`	read-write bind mount, `dst` defaults to `src`
`.ro_bind(src, dst=None)`	read-only bind mount
`.ro_bind_try(src, dst=None)`	read-only bind mount, skipped if `src` is missing
`.tmpfs(path)`	empty in-memory directory at `path`
`.proc(path="/proc")`	mount procfs
`.dev(path="/dev")`	mount a minimal `/dev`
`.setenv(**vars)`	set environment variables
`.clearenv()`	unset every variable set before it, defaults included
`.chdir(path)`	working directory
`.die_with_parent()`	kill the command when its parent exits
`.network(on)`	allow network, off by default
`.timeout(seconds)`	kill after this long
`await .run(argv, env=None)`	run `argv`, returns a `cycls.SandboxResult`

cycls.Sandbox() already mounts /tmp, /dev and /proc and dies with its parent. cycls.SandboxResult carries stdout and stderr as bytes, the exit code, timed_out, and .output, both streams decoded into one string. env= is the environment of bwrap itself, not of the command. Without it, bwrap runs with your app’s full environment, secrets included, so pass a minimal one as the example does.

Programmatic control

notes.local()              # Docker with hot reload
notes.local(watch=False)   # Docker, no watcher
notes.deploy()             # production

For python notes.py to serve, guard it the usual way:

if __name__ == "__main__":
    notes.local()

Agents

The chat layer on top of apps: a managed model loop, tools and a web UI.

Get started

Functions

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Apps

The decorator

Identity

Storage

Serving a front end

Running untrusted commands

Programmatic control

Next

Agents

​The decorator

​Identity

​Storage

​Serving a front end

​Running untrusted commands

​Programmatic control

​Next

Agents

The decorator

Identity

Storage

Serving a front end

Running untrusted commands

Programmatic control

Next