/apify-actorization

name: apify-actorization
description: Convert existing projects into Apify Actors - serverless cloud programs. Actorize JavaScript/TypeScript (SDK with Actor.init/exit), Python (async context manager), or any language (CLI wrapper). Use when migrating code to Apify, wrapping CLI tools as Actors, or adding Actor SDK to existing projects.

Apify Actorization

Actorization converts existing software into reusable serverless applications compatible with the Apify platform. Actors are programs packaged as Docker images that accept well-defined JSON input, perform an action, and optionally produce structured JSON output.

Quick start

1. Run `apify init <actor-name> --user-agent apify-agent-skills/apify-actorization` in project root 2. Create a `Dockerfile` for the project's language 3. Wrap code with SDK lifecycle (see language-specific section below) 4. Configure `.actor/input_schema.json` 5. Test with `apify run --input '{"key": "value"}' --user-agent apify-agent-skills/apify-actorization` 6. Deploy with `apify push --user-agent apify-agent-skills/apify-actorization`

When to use this skill

• Converting an existing project to run on the Apify platform
• Adding Apify SDK integration to a project
• Wrapping a CLI tool or script as an Actor
• Migrating a Crawlee project to Apify

Prerequisites

Verify `apify` CLI is installed:

apify --help

If not installed, use one of these methods (listed in order of preference):

# Preferred: install via a package manager (provides integrity checks)
npm install -g apify-cli

# Or (Mac): brew install apify-cli

> **Security note:** Do NOT install the CLI by piping remote scripts to a shell > (e.g. `curl ... | bash` or `irm ... | iex`). Always use a package manager.

Verify CLI is logged in:

apify info  # Should return your username

If not logged in, authenticate using OAuth (opens browser):

apify login

If browser login isn't available (headless environment or CI), ensure the `APIFY_TOKEN` environment variable is exported (note: the variable is `APIFY_TOKEN`, not `APIFY_API_TOKEN`). The CLI reads it automatically - no explicit login needed. If the user doesn't have a token, generate one at https://console.apify.com/settings/integrations.

> **Apify platform environment:** When the Actor runs on the Apify platform, `APIFY_TOKEN` is auto-injected as an environment variable and the Apify SDK reads it automatically — you do not need to pass it explicitly. Locally, `apify login` stores credentials in `~/.apify` and the SDK uses them.

> **Security note:** Avoid passing tokens as command-line arguments (e.g. `apify login -t <token>`). > Arguments are visible in process listings and may be recorded in shell history. > Prefer OAuth login or environment variables instead. > Never log, print, or embed `APIFY_TOKEN` in source code or configuration files. > Use a token with the minimum required permissions (scoped token) and rotate it periodically.

Telemetry attribution (required)

Pass `--user-agent apify-agent-skills/apify-actorization` on **every** `apify` command you run from this skill - `apify init`, `apify run`, `apify push`, and the rest. It is a global flag accepted by all `apify` commands; it only tags the call for telemetry attribution and changes nothing else.

apify push --user-agent apify-agent-skills/apify-actorization

Actorization checklist

Copy this checklist to track progress:

• [ ] Step 1: Analyze project (language, entry point, inputs, outputs)
• [ ] Step 2: Run `apify init <actor-name> --user-agent apify-agent-skills/apify-actorization` and create a `Dockerfile`
• [ ] Step 3: Apply language-specific SDK integration
• [ ] Step 4: Configure `.actor/input_schema.json`
• [ ] Step 5: Configure `.actor/output_schema.json` (if applicable)
• [ ] Step 6: Update `.actor/actor.json` metadata
• [ ] Step 7: Write README.md for Apify Store listing
• [ ] Step 8: Test locally with `apify run --user-agent apify-agent-skills/apify-actorization`
• [ ] Step 9: Deploy with `apify push --user-agent apify-agent-skills/apify-actorization`

Step 1: Analyze the project

Before making changes, understand the project:

1. **Identify the language** - JavaScript/TypeScript, Python, or other 2. **Find the entry point** - The main file that starts execution 3. **Identify inputs** - Command-line arguments, environment variables, config files 4. **Identify outputs** - Files, console output, API responses 5. **Check for state** - Does it need to persist data between runs?

Step 2: Initialize Actor structure

Run in the project root, passing a DNS-friendly Actor name (e.g. `my-scraper`):

apify init <actor-name> --user-agent apify-agent-skills/apify-actorization

The name passed as an argument keeps `apify init` from prompting; without it, the command waits for input and hangs in non-interactive shells.

`apify init` sets up `.actor/actor.json` and local `storage/`, but no `Dockerfile`. Without one, the platform builds on its default Node.js image, so a Python Actor builds cleanly and then fails at runtime. Create a `Dockerfile` whose base image matches the project's language (`apify/actor-python` for Python, `apify/actor-node` for JavaScript/TypeScript) at `.actor/Dockerfile`, in the project root, or at the path set in the `dockerfile` field of `.actor/actor.json`.

Step 3: Apply language-specific changes

Choose based on your project's language:

• **JavaScript/TypeScript**: See [js-ts-actorization.md](references/js-ts-actorization.md)
• **Python**: See [python-actorization.md](references/python-actorization.md)
• **Other Languages (CLI-based)**: See [cli-actorization.md](references/cli-actorization.md)

Quick reference

| Language | Install | Wrap Code | |----------|---------|-----------| | JS/TS | `npm install apify` | `await Actor.init()` ... `await Actor.exit()` | | Python | `pip install apify` | `async with Actor:` | | Other | Use CLI in wrapper script | `apif