Skip to main content

Develop Actors locally

Copy for LLM

To develop Actors locally, use the Apify CLI. You can use your own code editor and version control system. The CLI simulates the Apify environment so you can test the Actor before you deploy it.

Before you start

Create and run an Actor

To create and run your new Actor locally, use the following commands:

apify create my-actor-name
cd my-actor-name
apify run

For a detailed tutorial, see the Apify CLI quick start.

Explore the Actor

The apify create command creates a directory with boilerplate code. The exact structure and contents of the directory depend on the template that you choose.

my-actor/
├── .actor/
│   ├── actor.json           # Actor configuration
│   ├── input_schema.json
│   ├── output_schema.json
│   └── dataset_schema.json
├── src/
│   └── main.js              # Main logic of the Actor
├── storage/                 # Local storage
├── Dockerfile               # Container image definition
├── README.md
├── AGENTS.md                # Instructions for coding agents
└── package.json

.actor directory

The .actor directory contains the Actor configuration:

  • The actor.json file defines the Actor's name, description, version, and other settings. It links your local development project to an Actor on the Apify platform.
  • The input_schema.json file defines the input parameters for an Actor.
  • The output_schema.json file specifies where an Actor stores its output and defines templates for accessing that output.
  • The dataset_schema.json file defines the structure and presentation of data produced by an Actor.

Actor's input

Each Actor accepts an input object that tells it what to do. The object uses JSON format and lives in storage/key_value_stores/default/INPUT.json.

Local input comes from INPUT.json that you can edit manually. On the platform, input comes from the form generated by input_schema.json. Change the schema first, then update INPUT.json to match. Otherwise, the Actor works locally but fails validation on the platform.

Actor's output

The output_schema.json file defines where the Actor stores its results and how to access them. It builds on the dataset schema and the key-value store schema.

Actor's storage

The storage directory holds the data your Actor reads and writes when it runs locally. It mirrors the three storage types the Apify platform creates for every run:

PathPlatform equivalentContents
storage/datasets/default/The run's default datasetStructured results, one JSON file per item.
storage/key_value_stores/default/The run's default key-value storeFiles and data records. Works well for screenshots, PDFs, or persisting Actor state as JSON files.
storage/request_queues/default/The run's default request queueRequests the Actor enqueued.

Local storage persists between runs. To clear the default storages, run apify run --purge.

Deploy to the Apify platform

There are two ways to deploy your Actor code to the Apify platform:

  • Run the apify push command. It uploads the directory and starts a build. To control to which version the build belongs, use --version and --build-tag flags.
  • Host your Actor's source code in a Git repository. Then, to rebuild the Actor on every push, add a webhook. For details, see GitHub integration.

Next steps