Deploy an HTTP container

Run a small Python HTTP server using Oiy's catalog runtime image. This walkthrough uses CPU-only resources so you can learn the container lifecycle before choosing a GPU. It still allocates billable compute and storage when accepted. It is a learning server, not a production inference server.

1. Prepare your accountCopy Anchor Link

You need a verified account, sufficient balance, an enabled placement with compatible capacity, and a personal API key. Use a local terminal with curl, jq, and uuidgen. Supply OIY_API_KEY through your environment or secret store, then set the API origin:

export OIY_API_URL="https://oiy-ai-server.xsun.workers.dev"
curl --fail-with-body --silent --show-error \
  "$OIY_API_URL/api/catalog" > catalog.json
jq '{regions, templates, payment}' catalog.json

Review the Standard placement and current prices. A new account starts with zero credit; if top-ups are unavailable, an unfunded account cannot proceed. The catalog is not a capacity reservation. Read preview availability if your deployment differs from this reference.

2. Save your container configurationCopy Anchor Link

Save the following as service.json in a new working directory. Its image is the digest-pinned runtime used by the current built-in templates, including Python and the required runtime tools. You can compare it with templates in the catalog above before proceeding.

{
  "name": "hello-container",
  "region": "standard",
  "geography": "auto",
  "image": "oiy-ai-pytorch-images.xsun.workers.dev/oiy-ai-pytorch@sha256:75e3759275db19bdf2cf34b7dd59e2fc8bbf381faf91a194f05224a0f8d62302",
  "command": ["python", "-m", "http.server", "8080", "--bind", "0.0.0.0", "--directory", "/workspace"],
  "resources": { "gpuCount": 0, "cpu": 2, "memoryGb": 4 },
  "httpPort": 8080,
  "volumeGb": 20,
  "volumeMode": "service",
  "sleepAfterMinutes": 15
}

The command serves /workspace on port 8080. Files in that mount survive sleep and restart. Here the volume belongs to the service: deleting the service also deletes its workspace. Use independent storage when files must outlive a service.

3. Create once, then inspectCopy Anchor Link

The next request creates paid resources. Review your configuration and balance first. Generate an operation ID once; keep it unchanged when retrying this exact request.

CREATE_REQUEST_ID="$(uuidgen)"
curl --fail-with-body --silent --show-error \
  "$OIY_API_URL/api/services" \
  -H "Authorization: Bearer $OIY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CREATE_REQUEST_ID" \
  --data-binary @service.json > created.json

Continue only after curl succeeds. Creation returns a bare service object; save its ID:

SERVICE_ID="$(jq -er '.id' created.json)"
curl --fail-with-body --silent --show-error \
  "$OIY_API_URL/api/services/$SERVICE_ID" \
  -H "Authorization: Bearer $OIY_API_KEY" > service-state.json
jq '.service | {id, status, allocated, error, endpoint}' service-state.json

Repeat the GET request until the service is running. queued and starting are intermediate states. If it enters error, inspect events and logs. A failed or interrupted create request can have an uncertain outcome: inspect your account before retrying with the same operation ID. Do not generate another ID just because the first response was lost.

4. Open the authenticated endpointCopy Anchor Link

Use the endpoint returned by the service:

OIY_SERVICE_ENDPOINT="$(jq -er '.service.endpoint' service-state.json)"
curl --fail-with-body --silent --show-error \
  "$OIY_SERVICE_ENDPOINT" \
  -H "Authorization: Bearer $OIY_API_KEY"

You should receive an HTML directory listing of the workspace, or its index.html if one exists. A running service can still be initializing its application. For 503, follow Retry-After and check the logs. Do not place your API key in a URL. Browser launch is a separate console flow.

5. Pause and confirm releaseCopy Anchor Link

STOP_REQUEST_ID="$(uuidgen)"
curl --fail-with-body --silent --show-error \
  "$OIY_API_URL/api/services/$SERVICE_ID/actions" \
  -H "Authorization: Bearer $OIY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $STOP_REQUEST_ID" \
  --data '{"action":"stop"}'

Repeat the service GET from step 3. Wait for status: "sleeping" and allocated: false; a stop acknowledgement alone does not prove compute has been released. Compute charges end after confirmed release. Retained storage remains billable. Avoid requesting the HTTP endpoint while checking sleep: that request can wake the service.

6. Resume when neededCopy Anchor Link

START_REQUEST_ID="$(uuidgen)"
curl --fail-with-body --silent --show-error \
  "$OIY_API_URL/api/services/$SERVICE_ID/actions" \
  -H "Authorization: Bearer $OIY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $START_REQUEST_ID" \
  --data '{"action":"start"}'

Resuming allocates compute again, subject to balance and capacity. Wait for running, then access the endpoint. Files in /workspace remain; the Python process starts again. Pause again when finished. To stop storage charges too, back up any files and delete this service through the console; its service-owned workspace will be removed.

Move to a GPU workloadCopy Anchor Link

For a guided GPU calculation with the built-in runtime, continue with Run a GPU notebook.

Choose an available GPU profile, replace the learning server with your application command, and use the matching image dependencies. A GPU resource configuration alone does not turn this file server into an AI application. Long jobs should use activity protection.

sleepAfterMinutes: 15 configures automatic idle sleep. It does not mean an active connection or protected task is killed at fifteen minutes. gpuCount: 0 means CPU-only compute; sleeping with no allocation is scale-to-zero.