Serve a FastAPI app

This guide is for developers who want a web service rather than a chat product. You will build a notes API with sign-in, per-user storage and a single-page front end, then deploy it. Prerequisites: CYCLS_API_KEY, and Docker if you want to run locally.

1. The smallest app

api.py

import cycls


@cycls.app()
def api():
    from fastapi import FastAPI

    app = FastAPI()

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

    return app

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

The decorated function returns an ASGI application. It runs inside the container at startup, so import heavy dependencies in the body rather than at module level.

@cycls.app(auth=cycls.Clerk())
def api():
    from fastapi import FastAPI

    app = FastAPI()

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

    return app

api.auth is a FastAPI dependency. A request without a valid token gets 401. Any OIDC provider works with cycls.JWT(jwks_url=...). See Authentication.

3. Add per-user storage

Storage needs a volume at /workspace.

notes_data = cycls.Volume("notes-data")


@cycls.app(auth=cycls.Clerk(), volumes={"/workspace": notes_data})
def api():
    from fastapi import FastAPI
    from pydantic import BaseModel
    from uuid import uuid4

    app = FastAPI()

    class NoteIn(BaseModel):
        title: str = ""
        body: str

    @app.post("/notes")
    async def create(note: NoteIn, ws=api.workspace):
        record = {"id": uuid4().hex[:12], **note.model_dump()}
        await cycls.DB(ws).put(f"docs/{record['id']}", record)
        return record

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

    @app.delete("/notes/{note_id}")
    async def delete(note_id: str, ws=api.workspace):
        await cycls.DB(ws).delete(f"docs/{note_id}")
        return {"ok": True}

    return app

api.workspace resolves the authenticated user’s own scope, so no route needs to filter by user id. Two users calling GET /notes see different data.

4. Bundle a front end

Put the HTML beside the Python file and copy it into the image.

from pathlib import Path

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


@cycls.app(
    image=cycls.Image().copy(HTML, "index.html"),
    auth=cycls.Clerk(),
    volumes={"/workspace": notes_data},
)
def api():
    from fastapi import FastAPI
    from fastapi.responses import HTMLResponse

    app = FastAPI()

    @app.get("/")
    async def index():
        pk = api._auth_provider.resolve(api.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 HTML works locally and in production without a build step. The front end sends the token it gets from Clerk as Authorization: Bearer <token>.

5. Search with an inverted index

cycls.DB has no query language, so build the index you need. Prefix scans are the primitive.

docs/{id}            -> the note
idx/{term}/{id}      -> 1

import re

TOKEN = re.compile(r"[a-z0-9]+")


def tokenize(text):
    return set(TOKEN.findall(text.lower()))


@app.get("/search")
async def search(q: str, ws=api.workspace):
    db = cycls.DB(ws)
    ids = None
    for term in tokenize(q):
        prefix = f"idx/{term}/"
        hits = {k.removeprefix(prefix) async for k, _ in db.items(prefix=prefix)}
        ids = hits if ids is None else ids & hits
        if not ids:
            return []
    return [await db.get(f"docs/{i}") for i in ids or []]

Write the document and its index entries together:

import asyncio


@app.post("/notes")
async def create(note: NoteIn, ws=api.workspace):
    db = cycls.DB(ws)
    record = {"id": uuid4().hex[:12], **note.model_dump()}
    terms = tokenize(f"{record['title']} {record['body']}")
    await asyncio.gather(
        db.put(f"docs/{record['id']}", record),
        *[db.put(f"idx/{t}/{record['id']}", 1) for t in terms],
    )
    return record

These writes are not transactional. If the process dies between the document write and an index write, the index is incomplete. For a small app, rebuild the index on demand. For a larger one, write the document first and treat the index as derived state you can regenerate.

6. Run untrusted commands

cycls.Sandbox wraps bubblewrap with a read-only root, a cleared environment, and no network unless you enable it.

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


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

Only the caller’s own workspace is bound, so one user’s command cannot see another user’s files.

7. Deploy

cycls deploy api.py
# https://api.cycls.ai

cycls logs api -f
cycls volume ls notes-data

App or agent

Need	Use
A REST API or dashboard you design	`@cycls.app`
A chat product with a model loop, tools and files	`@cycls.agent`
Both	`@cycls.agent` plus custom routes on `.server`

An agent is an app, so you can add routes to an agent with @my_agent.server.api_route(...) instead of deploying two services.

Batch jobs

Fan work across instances with map.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Serve a FastAPI app

1. The smallest app

3. Add per-user storage

4. Bundle a front end

5. Search with an inverted index

6. Run untrusted commands

7. Deploy

App or agent

Next

Batch jobs

​1. The smallest app

​2. Add sign-in

​3. Add per-user storage

​4. Bundle a front end

​5. Search with an inverted index

​6. Run untrusted commands

​7. Deploy

​App or agent

​Next

Batch jobs

1. The smallest app

2. Add sign-in

3. Add per-user storage

4. Bundle a front end

5. Search with an inverted index

6. Run untrusted commands

7. Deploy

App or agent

Next