Hosted Runtime

Deploy a tool server to a sandboxed Lambda in Convilyn's AWS account — no infrastructure of your own to run. Pairs with rollback and logs for full lifecycle control.

The convilyn-author deploy --hosted, rollback, and logs CLI verbs target the Convilyn-Hosted Author Runtime. The CLI source is at sdk-author/src/convilyn_sdk/cli/main.py:247-393; the ops view (smoke checks, alarms, rollback drills) lives in backend-api/docs/RUNBOOK_AUTHOR_RUNTIME.md.

If you prefer to run your own host (any HTTPS-reachable endpoint), use convilyn-author push --endpoint-url <url> instead — it's the BYO ("bring your own") path and stays unaffected by anything on this page.

Prerequisites

• Platform feature flag AUTHOR_RUNTIME_ENABLED=true on the target environment (ops controls this; check with #dev-platform if you get a 501).
• A logged-in convilyn-author CLI: convilyn-author auth login.
• A server.py exporting a ToolServer instance (see Tool Servers).
• Optional: a workflow.py defining a WorkflowSpec that calls into the server's tools (see Workflows).

Quick deploy

convilyn-author deploy --hosted --region us-east-1

Without --hosted, the command exits early with a pointer at push — deploy never silently means two different things.

Expected output:

Deploying to Convilyn-Hosted Runtime in us-east-1...
Runtime provisioned: art_3f1b9a2e (active)
Endpoint URL: https://abc123.lambda-url.us-east-1.on.aws/
Workflow registered: my_text_analyzer
Use 'convilyn-author logs <runtime_id>' to follow runtime logs,
    'convilyn-author rollback <runtime_id>' to revert.

What happens behind the scenes (each is owned by a stable backend contract — the SDK only consumes the result):

1. The CLI calls server.synth().to_dict() to build the manifest from your ToolServer definition.
2. If workflow.py exists in the cwd, it is compiled and submitted alongside.
3. The platform provisions a sandboxed Lambda + writes the AuthorRuntime DDB row and returns a 202 with runtime_id, endpoint_url, status, and (when a workflow accompanies) workflow_id.
4. The router URL (endpoint_url) is now the public entry the Convilyn API forwards /mcp traffic to.

Options

Response fields

Unpacked at cli/main.py:319-329:

Inspecting logs

convilyn-author logs art_3f1b9a2e
convilyn-author logs art_3f1b9a2e --since 15m
convilyn-author logs art_3f1b9a2e --since 1h --limit 500

Source: cli/main.py:360-393. The platform reads from the runtime's CloudWatch log group and emits one line per entry:

[2026-05-28T09:14:22Z] INFO tool=analyze_text duration_ms=42
[2026-05-28T09:14:23Z] ERROR parse_document failed: encrypted PDF rejected

Empty windows print a single notice (No log entries for art_3f1b9a2e in the requested window.) instead of an empty stream — so a quiet runtime is unambiguously different from a missing one.

Options

Rolling back

When a fresh deploy misbehaves:

convilyn-author rollback art_3f1b9a2e

Source: cli/main.py:332-358. The Lambda alias atomically flips to the previously active image; subsequent rollbacks continue stepping back through retained image versions (the ECR lifecycle policy keeps the most recent 20 tags per author — see backend-api/docs/RUNBOOK_AUTHOR_RUNTIME.md for the policy).

Expected output:

Rolling back art_3f1b9a2e...
Rollback complete: now-active version 3 (active)

The traffic cutover is single-flip, not gradual — pair with logs immediately after to confirm the previous version is healthy on real traffic.

Manifest skeleton

The manifest is whatever server.synth().to_dict() produces; you do not edit it by hand. A typical server.py:

# server.py
from convilyn_sdk import ToolServer

server = ToolServer(
    name="my-analyzer",
    description="Document analysis tools",
    version="0.1.0",
)


@server.tool(description="Analyze text length and word count")
async def analyze_text(text: str) -> dict:
    return {"length": len(text), "words": len(text.split())}


if __name__ == "__main__":
    server.run()

The CLI imports this file, calls server.synth(), and includes the resulting image_uri field (resolved against the platform's per-author ECR repository) in the deploy payload.

Troubleshooting

Ops escalation path (alarm + log-group runbooks): backend-api/docs/RUNBOOK_AUTHOR_RUNTIME.md.

Related

• Tool Servers — what gets packaged into the deployed image
• Workflows — the spec that gets registered alongside on deploy
• Templates — start from a published starter instead of from scratch