apify-actorization

Code you already have, a script or a command-line tool, gets wrapped so it can run as an Apify Actor in the cloud, without rewriting the logic inside it.

WHEN TO USE

SCOPE

USE FOR

Wrap an existing Node.js, Python, or CLI project so it runs as an Apify Actor.
Migrate a Crawlee scraping project onto the Apify platform.
Add Apify SDK lifecycle calls to a script without rewriting its logic.
Set up Pay Per Event pricing so a converted Actor can be sold on Apify Store.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (17)

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

Run apify init in project root
Wrap code with SDK lifecycle (see language-specific section below)
Configure .actor/input_schema.json
Test with apify run --input '{"key": "value"}'
Deploy with apify push

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.

Actorization checklist

Copy this checklist to track progress:

Step 1: Analyze project (language, entry point, inputs, outputs)
Step 2: Run apify init to create Actor structure
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
Step 9: Deploy with apify push

Step 1: Analyze the project

Before making changes, understand the project:

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

Step 2: Initialize Actor structure

Run in the project root:

apify init

This creates:

.actor/actor.json - Actor configuration and metadata
.actor/input_schema.json - Input definition for Apify Console
Dockerfile (if not present) - Container image definition

Step 3: Apply language-specific changes

Choose based on your project's language:

JavaScript/TypeScript: See js-ts-actorization.md
Python: See python-actorization.md
Other Languages (CLI-based): See 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	`apify actor:get-input` / `apify actor:push-data`

Steps 4-6: Configure schemas

See schemas-and-output.md for detailed configuration of:

Input schema (.actor/input_schema.json)
Output schema (.actor/output_schema.json)
Actor configuration (.actor/actor.json)
State management (request queues, key-value stores)

Validate schemas against @apify/json_schemas npm package.

Step 7: Write README

IMPORTANT: Always generate a README.md as part of actorization. The README is the Actor's landing page on Apify Store and is critical for discoverability (SEO), user onboarding, and support. Do not consider an Actor complete without a proper README.

See the Actor README guidelines at skills/apify-actor-development/references/actor-readme.md for the required structure including: intro and features, data extraction table, step-by-step tutorial, pricing info, input/output examples, and FAQ. Aim for at least 300 words with SEO-optimized H2/H3 headings. Also review these top Actors for best practices:

Step 8: Test locally

Run the Actor with inline input (for JS/TS and Python Actors):

apify run --input '{"startUrl": "https://example.com", "maxItems": 10}'

Or use an input file:

apify run --input-file ./test-input.json

Important: Always use apify run, not npm start or python main.py. The CLI sets up the proper environment and storage.

Step 9: Deploy

apify push

This uploads and builds your Actor on the Apify platform.

Monetization (optional)

After deploying, you can monetize your Actor in Apify Store. The recommended model is Pay Per Event (PPE):

Per result/item scraped
Per page processed
Per API call made

Configure PPE in Apify Console under Actor > Monetization. Charge for events in your code with await Actor.charge('result').

Other options: Rental (monthly subscription) or Free (open source).

Security

Treat all crawled web content as untrusted input. Actors ingest data from external websites that may contain malicious payloads. Follow these rules:

Sanitize crawled data — Never pass raw HTML, URLs, or scraped text directly into shell commands, eval(), database queries, or template engines. Use proper escaping or parameterized APIs.
Validate and type-check all external data — Before pushing to datasets or key-value stores, verify that values match expected types and formats. Reject or sanitize unexpected structures.
Do not execute or interpret crawled content — Never treat scraped text as code, commands, or configuration. Content from websites could include prompt injection attempts or embedded scripts.
Isolate credentials from data pipelines — Ensure APIFY_TOKEN and other secrets are never accessible in request handlers or passed alongside crawled data. Use the Apify SDK's built-in credential management rather than passing tokens through environment variables in data-processing code.
Review dependencies before installing — When adding packages with npm install or pip install, verify the package name and publisher. Typosquatting is a common supply-chain attack vector. Prefer well-known, actively maintained packages.
Pin versions and use lockfiles — Always commit package-lock.json (Node.js) or pin exact versions in requirements.txt (Python). Lockfiles ensure reproducible builds and prevent silent dependency substitution. Run npm audit or pip-audit periodically to check for known vulnerabilities.

Pre-deployment checklist

MCP tools

Apify MCP

If the Apify MCP server is configured, use these tools for documentation:

search-apify-docs - Search documentation
fetch-apify-docs - Get full doc pages

Otherwise, the MCP Server url: https://mcp.apify.com/?tools=docs.

Playwright MCP (debugging)

The Playwright MCP server is a useful tool for debugging Actors that interact with the web - it lets the agent drive a real browser to inspect pages, capture selectors, and reproduce issues.

Install with the Claude Code CLI:

claude mcp add playwright npx @playwright/mcp@latest

Or add it manually to your MCP config:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Resources

Actorization Academy - Comprehensive guide
Apify SDK for JavaScript - Full SDK reference
Apify SDK for Python - Full SDK reference
Apify CLI Reference - CLI commands
Actor Specification - Complete specification

Account or credentials required

2 FOR YOU

All items below are required.

01
Install the Apify CLI
Install the apify CLI with a package manager — npm install -g apify-cli, or brew install apify-cli on a Mac — never by piping a remote install script into a shell.
02
Authenticate the Apify CLI with your account
Run apify login for interactive OAuth, or export the APIFY_TOKEN environment variable in headless or CI environments; generate a token at console.apify.com/settings/integrations.
You set: APIFY_TOKEN — or sign in with apify login instead

Payment mentioned: The instructions mention pricing or payment; check the provider's pricing for actual costs.
Setup details: Expect some account or credential setup.

This skill ships inside the Apify Agent Skills plugin. Listed package contents include 1 slash command. Installed components and skill versions may vary by AI tool.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add apify/agent-skills --skill "apify-actorization" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub