WARP Service

A WARP Service is a long-running FastAPI application (or daemon) that runs inside the Arpia Platform and is exposed through a built-in reverse-proxy gateway. Unlike a Reasoning Flow or an Action — which run on demand and finish — a WARP Service stays up, keeps state, and serves requests continuously under a stable URL.

Use a WARP Service when you need:

• A persistent HTTP API (webhooks, callbacks, custom endpoints).
• A background worker or daemon that must keep running between requests.
• A long-lived process that other parts of your Work Area can call by URL.

📘

WARP vs. other project types

WARP is a dedicated project type. The WARP object is exclusive to WARP projects, and the platform sets warp_service_kind automatically when you create one — so you don't configure the runtime by hand.

How it works

Each WARP Service is published behind the platform gateway at:

/warp/<ws_token>/<your-route>

• <ws_token> is the Work Area token that scopes the service.
• <your-route> is any path your FastAPI app defines.

The gateway (arpia_warp) is a FastAPI reverse-proxy that routes inbound traffic to the pod running your service, with idempotent retries, structured errors, and upstream cache invalidation on timeout.

Creating a WARP Service

1. Create a new project and choose WARP Service from the Project Type dropdown (also available in the edit-project form).
2. The platform seeds the project with a starter main.py and an arpia_service.json manifest.
3. Your canonical entry point is index.py. It ships with a documented background-task pattern so the Codex Assistant understands the service shape.

📘

Entry point

index.py is the canonical entry point for a WARP Service. Legacy index.py / welcome.py seeding from other project types is skipped for WARP projects.

The runtime runs on the arpia-warp-python Docker image, registered in the platform's Docker catalog. FastAPI is auto-installed at pod start, so you can import it immediately.

Lifecycle

Manage the service from the project sidebar toolbar — Start, Stop, Restart, Console, and URL — or programmatically through the lifecycle endpoints:

Restart always redeploys using your latest saved code. The platform blocks termination of the old pod until it has read the IP of the new one, so traffic resolves cleanly across the swap.

Status semantics

The gateway distinguishes a service that is down from one that is briefly unavailable:

• 404 — the service is stopped or failed (not currently serving).
• 503 — a transient condition (e.g. the pod is still coming up).

This lets callers tell "not running" apart from "try again shortly."

Monitoring and logs

• WARP services appear in check-project-running, with the running node highlighted in the ReactFlow view.
• They are listed in the process list (mdl-proc-list) with a Kill action and are included in the check-running pollers.
• The Console button opens a live log tail in the Workshop console; log resolution is keyed by label.

Notes

• WARP service metadata is stored in the _ws_k8_warp_services table.
• The service runs as a top-level arpia-warp-server process under systemd (not Docker-managed).