Develop, debug, and deploy Apify Actors - serverless cloud programs for web scraping, automation, and data processing. Use when creating new Actors, modifying existing ones, or troubleshooting Actor code.

Apify Actor development Important: Before you begin, fill in the generatedBy property in the meta section of .actor/actor.json . Replace it with the tool and model you're currently using, such as "Claude Code with Claude Sonnet 4.5". This helps Apify monitor and improve AGENTS.md for specific AI tools and models. What are Apify Actors? Actors are serverless programs inspired by the UNIX philosophy programs that do one thing well and can be easily combined to build complex systems. They're packaged as Docker images and run in isolated containers in the cloud. Core Concepts: Accept well defined JSON input Perform isolated tasks (web scraping, automation, data processing) Produce structured JSON output to datasets and/or store data in key value stores Can run from seconds to hours or even indefinitely Persist state and can be restarted Prerequisites and setup (mandatory) Before creating or modifying Actors, verify that apify CLI is installed apify help . If it is not installed, use one of these methods (listed in order of preference): 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. When the apify CLI is installed, check that it is logged in with: If not logged in, authenticate using OAuth (opens browser): If browser login isn't available (headless environment or CI), the CLI automatically reads APIFY TOKEN from the environment. Ensure the env var is exported and run any apify command no explicit login needed. If the user doesn't have a token, generate one at https://console.apify.com/settings/integrations. 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 environment variables or interactive login 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. Template selection IMPORTANT: Before starting Actor development, always ask the user which programming language they prefer: JavaScript Use apify create <actor name t project empty TypeScript Use apify create <actor name t ts empty Python Use apify create <actor name t python empty Use the appropriate CLI command based on the user's language choice. Additional packages (Crawlee, Playwright, etc.) can be installed later as needed. Quick start workflow 1. Create Actor project Run the appropriate apify create command based on user's language preference (see Template selection above) 2. Install dependencies (verify package names match intended packages before installing) JavaScript/TypeScript: npm install (uses package lock.json for reproducible, integrity checked installs — commit the lockfile to version control) Python: pip install r requirements.txt (pin exact versions in requirements.txt , e.g. crawlee==1.2.3 , and commit the file to version control) 3. Implement logic Write the Actor code in src/main.py , src/main.js , or src/main.ts 4. Configure schemas Update input/output schemas in .actor/input schema.json , .actor/output schema.json , .actor/dataset schema.json 5. Configure platform settings Update .actor/actor.json with Actor metadata (see [references/actor json.md](references/actor json.md)) 6. Write documentation Create comprehensive README.md for the marketplace (see [references/actor readme.md](references/actor readme.md) — this is mandatory, not optional) 7. Test locally Run apify run to verify functionality (see Local testing section below) 8. Deploy Run apify push to deploy the Actor on the Apify platform (Actor name is defined in .actor/actor.json ) 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. Best practices ✓ Do: Use apify run to test Actors locally (configures Apify environment and storage) Use Apify SDK ( apify ) for code running on the Apify platform Validate input early with proper error handling and fail gracefully Use CheerioCrawler for static HTML (10x faster than browsers) Use PlaywrightCrawler only for JavaScript heavy sites Use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls Implement retry strategies with exponential backoff Use proper concurrency: HTTP (10 50), Browser (1 5) Set sensible defaults in .actor/input schema.json Define output schema in .actor/output schema.json Clean and validate data before pushing to dataset Use semantic CSS selectors with fallback strategies Respect robots.txt, ToS, and implement rate limiting Always use apify/log package — censors sensitive data (API keys, tokens, credentials) Implement readiness probe handler (required if your Actor uses standby mode) ✗ Don't: Use npm start , npm run start , npx apify run , or similar commands to run Actors (use apify run instead) Assume local storage from apify run is pushed to or visible in Apify Console — it is local only; deploy with apify push and run on the platform to see results in Apify Console Rely on Dataset.getInfo() for final counts on Cloud Use browser crawlers when HTTP/Cheerio works Hard code values that should be in input schema or environment variables Skip input validation or error handling Overload servers use appropriate concurrency and delays Scrape prohibited content or ignore Terms of Service Store personal/sensitive data unless explicitly permitted Use deprecated options like requestHandlerTimeoutMillis on CheerioCrawler (v3.x) Use additionalHttpHeaders use preNavigationHooks instead Pass raw crawled content into shell commands, eval() , or code generation functions Use console.log() or print() instead of the Apify logger — these bypass credential censoring Disable standby mode without explicit permission Logging See [references/logging.md](references/logging.md) for complete logging documentation including available log levels and best practices for JavaScript/TypeScript and Python. Commands Remote Actor calls When running Actors remotely, use this flow: 1. Search for the right Actor with apify actors search "<query " . 2. Inspect its README with apify actors info <actor readme . 3. Inspect its input schema with apify actors info <actor input . 4. Call it with either input file input.json or quoted inline JSON. Actor input is one JSON object, not an array. input accepts inline JSON object input only; wrap inline JSON in quotes to avoid shell parsing issues, for example input '{"startUrls":[{"url":"https://example.com"}]}' . For JSON files or complex inputs, use input file input.json . If no dedicated Actor exists for your target, search Apify Store for community options before building from scratch. Local and runtime commands Always use apify run to test Actors locally. Do not use npm run start , npm start , yarn start , or other package manager commands these will not properly configure the Apify environment and storage. Inside a running Actor, prefer the SDK ( Actor.getInput() / Actor.get input() , Actor.pushData() / Actor.push data() , Actor.setValue() / Actor.set value() ) over the equivalent apify actor runtime subcommands. Apify platform environment When the Actor runs on the Apify platform, the API token is automatically available via the APIFY TOKEN environment variable (note: the variable is APIFY TOKEN , not APIFY API TOKEN ). The Apify SDK reads it automatically, so you do not need to pass it explicitly. Locally, run apify login once and the SDK will use your stored credentials. Local testing When testing an Actor locally with apify run , provide input data by creating a JSON file at: This file should contain the input parameters defined in your .actor/input schema.json . The actor will read this input when running locally, mirroring how it receives input on the Apify platform. IMPORTANT Local storage is NOT synced to Apify Console: Running apify run stores all data (datasets, key value stores, request queues) only on your local filesystem in the storage/ directory. This data is never automatically uploaded or pushed to the Apify platform. It exists only on your machine. To verify results on Apify Console, you must deploy the Actor with apify push and then run it on the platform. Do not rely on checking Apify Console to verify results from local runs — instead, inspect the local storage/ directory or check the Actor's log output. Standby mode Standby mode enables Actors to work as API servers they remain ready in the background to handle HTTP requests. When to use Standby mode: Use Standby when the Actor must handle interactive, real time HTTP requests — API endpoints, webhook receivers, real time data lookups, MCP servers, or scraping APIs serving on demand single URL requests. When building a Standby Actor, set usesStandbyMode: true in .actor/actor.json and implement an HTTP server. See [references/standby mode.md](references/standby mode.md) for configuration, environment variables, complete code examples, and operational limits. Project structure Actor configuration See [references/actor json.md](references/actor json.md) for complete actor.json structure and configuration options. Input schema See [references/input schema.md](references/input schema.md) for input schema structure and examples. Output schema See [references/output schema.md](references/output schema.md) for output schema structure, examples, and template variables. Dataset schema See [references/dataset schema.md](references/dataset schema.md) for dataset schema structure, configuration, and display properties. Key value store schema See [references/key value store schema.md](references/key value store schema.md) for key value store schema structure, collections, and configuration. Actor README IMPORTANT: Always generate a README.md as part of Actor development. 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 [references/actor readme.md](references/actor readme.md) for the required str

apify-actor-development