Script directives

Important general informations on how to create and configure the environment your custom scripts will run in.


Before reading this guide

If you don't know how to create and manage custom scripts on Phantombuster, you might find our article on how to manage your custom scripts useful.

Script directives

All Phantombuster scriptscript - The source code that will be executed by NodeJS in the cloud, using Puppeteers, Buster library, and more.s must start with a few lines called script directives. They let you configure the environment in which the script will run.

Here is a typical example:

// Phantombuster configuration {
"phantombuster package: 5"
"phantombuster command: nodejs"
"phantombuster dependencies: lib-Foo.js"
"phantombuster flags: save-folder"
// }

Each line is a directive and will be explained below. Their order is of no importance.

Packages ("phantombuster package")

The phantombuster package is one of the most important script directives. It allows you to select which NPM modules and binaries are bundled with your agent's script. It is mandatory to specify a package.

"phantombuster package: 5"

We listed available packages & modules in the next tutorial.

Binaries ("phantombuster command")

List of available binaries

Scripts can be launched on our platform by one of the following binaries:

  • NodeJS — Execute your scripts in V8, Chrome's JavaScript runtime — Allows you to control Headless Chrome
  • PhantomJS — Headless, scriptable WebKit browser (where Phantombuster originally got its name from) — Now DEPRECATED, please use NodeJS instead
  • CasperJS — Framework built on top of PhantomJS to write test and navigation scenarios — Now DEPRECATED, please use NodeJS instead

Telling your script which binary to use

Use the phantombuster command directive to select the binary you want, for example:

"phantombuster command: nodejs"

The available keywords are: nodejs, phantomjs and casperjs.


Always specify a binary

If you omit the phantombuster command directive, Phantombuster will launch CasperJS by default. Always specify which binary to use!

Writing your own modules ("phantombuster dependencies")

Sometimes your custom scriptscript - The source code that will be executed by NodeJS in the cloud, using Puppeteers, Buster library, and more. becomes big and the size of its source code makes it difficult to understand and maintain.

That's the time when you need to split your code into multiple files. Phantombuster allows you to create modules that you can require() into your agent's code.


How to create a new module

To create a new module, log in, go to your developer page, click "Create script" and enter the desired name of your module (module names should be prefixed with lib-).

Example of a simple module:

module.exports = {
  foo: () => {

Example of an agent script using the module shown above:

"phantombuster command: node"
"phantombuster package: 5"
"phantombuster dependencies: lib-Foo.js, lib-OtherModule.js"

require("./lib-Foo").foo() // outputs "bar"

As you can see, you must indicate on which modules your agent's script is dependent before being able to require() them.

When calling require(), do not forget to add ./ in front of the name of your module. If your agent's script has multiple dependencies, specify a list of module names separated by commas.

The dependency list is case sensitive and must contain the exact modules names including their extension.

Flags ("phantombuster flags")

The phantombuster flags directive allows you to enable miscellaneous features of the Phantombuster platform.

For now there is only one flag named save-folder which makes sure the files you have downloaded to your agent's disk get saved to your account's cloud storage before the script terminates.

"phantombuster flags: save-folder"

This lets you write your scripts without bothering to remember to call buster.saveFolder() at the end.

In what environment do my scripts run?

Your scripts are executed in Linux containers (they are similar to very light virtual machines).

Available to you are a few gigabytes of RAM, a few gigabytes of hard disk space and a fast internet connection. These are temporary resources that are freed right after your agent finishes its job.

What's important to know is that files written on your agent's disk will be lost when it exits. To keep files, save them to your persistent storage using our BusterJS library or by adding the line "phantombuster flags: save-folder" at the top of your script.

More technical details (for the nerds):

  • The container engine is Docker
  • Containers are running Debian
  • Agents always start in /home/phantom/agent which is empty
  • Agents run under the user phantom



We wrote a complete guide on how to code a custom script using TypeScript!

What’s Next