Pinokio is your Localhost Cloud: run anything locally—apps, AI, agents, and web servers—on your own machines with a full toolchain built in.

All-in-one environment ready to run ANY web app/AI servers on your PC (Including Python, Node.js, Git, Conda, etc)

A lot of desktop apps nowadays are wrappers that mainly connect to some cloud service. Pinokio is the exact opposite.

In fact, the main philosophy of Pinokio is: "The Localhost Cloud", a cloud that runs privately and locally on your machines.

Pinokio is like Vercel, but for localhost.

Practically speaking, it's a platform that lets you host all kinds of web apps and AI apps on your personal computer, and use like they're from public web.

In order to facilitate this, the platform comes with everything you need to build and run anything on your machine.

• Python
• Node.js
• Git
• UV
• Conda
• Homebrew
• FFMpeg
• Caddy (Reverse Proxy)
• Can programmatically install ANYTHING additional.

Thanks to the built in package managers like Conda and Homebrew, it is extremely simple to automatically install additional packages.

Of course, Pinokio has full access to shell commands so you can pretty much install anything even when there are no pre-packaged binaries.

Pinokio lets you not only browse websites, but also the backend and your file system, directly in the UI.

Pionkio lets you use any CLI app or agent over web UI. No need to enter any command, just run the CLI apps like you surf the web.

Pinokio automatically turns any CLI app into a server process so you can use them like web surfing.

You can also access them from any web browser since it's just a web page after all.

Each agent is a tab. Spin up as many tabs as you want for the same project.

Agents sends you push notifications when they're done, just like an instant messenger.

All you need to do is just open the CLI agents in Pinokio, and you INSTANTLY get push notifications when they are done, REGARDLESS of which CLI agent.

No more worrying about when the agents are done working. They literally message you.

Create a project AND kick off the agent with 1-click.

The built-in browser lets you copy and paste any region into CLI.

The best part is, it works for ANY CLI agent.

You can connect to the machine from a remote device, such as your phone, and work on building, without ever touching your PC keyboard.

The terminal can be opened by simply entering the URL and anyone can jump in and collaborate on the same terminal simultaneously.

It's very simple to create your own gateway.

First, just create a folder under ~/pinokio/plugin like this:

~/pinokio/plugin
└── crush
    ├── pinokio.js
    └── crush.png

Next, write a pinokio.js file like this:

module.exports = {
  // display title
  title: "Crush",
  // display icon (relative path)
  icon: "crush.png",
  // external link
  link: "https://github.com/charmbracelet/crush",
  run: [{
    method: "shell.run",
    params: {
      // The command to launch
      message: "npx -y @charmland/crush",
      // The path to launch the command from
      path: "{{args.cwd}}",
      // buffer size (default: 256)
      buffer: 1024,
      // allow input if input: true. otherwise an automated shell execution
      input: true
    }
  }]
}

module.exports = {
  title: "Crush",
  icon: "crush.png",
  run: [{
    method: "shell.run",
    params: {
      message: "npx -y @charmland/crush",
      path: "{{args.cwd}}",
      input: true
    }
  }]
}

That's all! Now you should:

1. The CLI app should show up in the 1-click launcher
2. The CLI app should show up in dev mode, so you can launch them inside each project

Built-in memory for ALL AI agents. No complicated infrastructure. All based on flat files. No setup required. Everything just works, automatically.

Everything that happens in terminals is stored in memory. This includes:

1. /logs/api: Automated script logs (Install script logs, launch script logs, etc.). The launch script logs contains the actual application execution logs.
2. /logs/dev: CLI agent logs. All the conversation history with AI agents like codex, claude code, gemini cli, etc.
3. /logs/shell: Actual shell usage. All user interaction with the terminal is logged.

Everything is stored as files. No database. No API. Just flat files. This means there is no extra infra needed, and ANY AI agent can access the memory simply by reading the files.

• CLI Agents: Codex CLI, Claude Code, Gemini CLI, etc.
• Standalone Agents: Cursor, Windsurf, etc.

Everything is stored as files under the logs folder inside the project folder. This means you can just copy the entire project folder to another machine and pick up where you left off.

Since the agents are instructed to automatically reference the logs, debugging is as easy as saying "Fix". No need to paste error messages--the agents should just figure out by accessing the memory. It just works.

Since everything is logged, every session can access the old history. This means you can start a new session and resume where you left off last session by asking the agent to first recall what happened so far.

All agents can access the same memory, since the "memory" is simply a bunch of log files.

This makes it easy to make multiple agents collaborate on tasks using the same memory, for example:

1. Start codex CLI and ask it to write down a detailed plan.
2. Start claude code and review plan from codex, and if nothing is wrong, build it.

• Launchers: Publish apps to run locally
• AI-Generated Launchers: Launchers are automatically generated when you build your apps in pinokio folders

Pinokio makes it easy to package any cloud app into a pack that can run locally.

1. Package an app in a launcher
2. Publish the packed repository to git hosting services
3. 1-Click download, install, and run.

While you can manually write the scripts that package the application, it's much simpler to just let an AI agent do it.

And Pinokio has this agent built-in. All you need to do is build apps inside the Pinokio folder

The Pinokio Packaging Agent seamlessly works with ANY AI coding agent:

• CLI Agents: Claude code, Codex CLI, Gemini CLI, etc.
• Standalone Applications: Cursor, Windsurf, etc.

Thanks to the "login with localhost" feature, it is as easy as 1 click to create github repositories and publish to them, which instantly makes your packaged apps available for download by other people.

Adaptive container elements that can become anything - AI, terminals, apps, remote machines.

Spin up a new cell with 1 click.

You can spin up multiple windows side by side. This lets you do all kinds of powerful things. For example,

Talk to AI agent on one cell, watch the generated app on another cell:

.

Run an app on one cell, watch its backend logs on another cell:

Run an app while monitoring processes with terminal apps (like top, htop, etc.)

You can keep creating as many cells as you want, each cell is independent from each other.

One click version control

Switch to any past version you prefer.

You can make git commits (save version) with one click

Create your own repository on Github with 1-click.

Publish your project to github with one click.

Simply by creating a project in Pinokio folders, you get version control out of the box.

Pinokio automatically creates a private web made up of all the machines on your office/home network (LAN --- Local Area Network)

Pinokio automatically discovers ALL servers running on your machine (localhost), regardless of whether it was launched by Pinokio or not.

For example, external applications that operate based on a server will be instantly accessible for surfing from Pinokio. Some examples:

• ComfyUI Desktop
• LMStudio
• Ollama
• Any Docker Container

Instantly discover and surf every machine on your LAN as if it's public web.

Instant HTTPS URLs for all your localhost apps, like https://comfyui.localhost

Custom domains in pinokio is super simple---the folder names are the domain names. That's it.

Give memorable domain names for locally installed apps. No more localhost URLs with ever-changing PORTs.

Regardless of which port the apps launch from, they will ALWAYS have the fixed HTTPS domain.

Simply by keeping Pinokio on, ALL apps running on your machine (even external 3rd party apps like Ollama, LMStudio, etc) gets an HTTPS url.

The convention is:

http://localhost:<PORT>

becomes

https://<PORT>.localhost

Examples:

1. Ollama: which runs on http://localhost:11434 automatically gets the url: https://11434.localhost
2. LM Studio: which runs on http://localhost:1234 automatically gets the url: https://1234.localhost
3. ComfyUI Desktop: which runs on http://localhost:8188 automatically gets the url: https://8188.localhost

What if you want to get custom domains for ANY web server running on your machine? Even the ones that have NOTHING to do with Pinokio? (Llamabarn, Ollama, LM Studio, ComfyUI Desktop, etc.) Simple, simply create a folder with the custom name and connect a port.

Here's an example where I instantly get a local web domain for a locally running LlamaBarn server (https://github.com/ggml-org/LlamaBarn):

1. Go to the network page
2. Find the server you want
3. Click "Get .localhost domain"
4. Enter the domain and wait
5. That's it! You can now start using https://WHATEVER.localhost directly in any browser.

Running web applications locally usually means dealing with a frustrating workflow: launch the server, wait for it to start up, then finally begin working. You can't leave everything running indefinitely, so this tedious cycle repeats every time you need the app. Public web apps solve this perfectly—just open a URL and start working instantly. The server is always ready.

What if we could have this exact experience for localhost apps? ---- If the app is not already running, automatically launch, and then redirect after launching when you enter the URL.

And that's what Auto-launch does!

When the app is not running already, it will automatically launch the app, and then redirect you it after launching.

When the app is already running, it will just work.

Pinokio lets you log into online services like Hugging Face, GitHub, X.com, etc. from Localhost apps.

This means your localhost app can:

1. Utilize online identity in the app logic (Example: Display the logged in user's profile and profile information in the web UI)
2. Access online resources that require authentication (Example: Download HuggingFace models that require login, Clone private GitHub repositories, etc.)
3. Publish to online from localhost apps: 1-Click publish a trained model to HuggingFace, 1-Click publish to github.)
4. and more

When you log into Huggingface from Pinokio, all your apps that run in Pinokio will automatically have HF_TOKEN environment set when launching. This means it's possible to:

1. Download private models from huggingface
2. Publish to huggingface

When you log into GitHub from Pinokio, without having to authenticate, you can simply run git commands or gh commands (Github CLI) to do things like:

1. Create repos on github
2. Clone private github repos
3. Publish to github

Pinokio can run in two different modes:

1. Desktop mode: The default pinokio desktop app.
2. Background mode: Launch Pinokio as a background process. Displays the Pinokio icon on the menubar, and opens the app in a regular browser.

You can switch back and forth from the settings page:

When you switch to background mode, Pinokio will relaunch as a menubar item (No desktop app) and open a localhost URL at http://localhost:42000

Now anyone can build a 1-click launcher for any project just with a prompt.

Step 1. Click "Create" from Pinokio home

Step 2. Enter "1 click launcher for project url or name", set the project name, select the AI agent/IDE to work with, and click "Create"

Step 3. Build using your favorite AI agent/IDE

Pinokio will automatically instruct whichever AI agent or IDE you use to automatically structure the project with a built-in launcher. Build your launcher with your AI.

Step 4. Launch

When the build has finished, switch to "Run" mode to launch the app using the created app its launcher.

Step 5. Publish

Use the built-in github publish feature to publish your launcher to github, and share with others.

It doesn't have to be about building a launcher for existing projects---you can create ANY project with 1-click launcher built-in!

All you need to do is initialize your project from Pinokio.

1. Click "Create" from Pinokio home
2. Enter some prompt and select an AI agent to open with
3. It should initialize a new project (with pinokio launcher built-in) and open the selected AI agent/IDE
4. Start building
5. once finished, open the "run" mode and check that the launcher and the app are working

Take any app and customize it to your liking:

1. Clone an app
2. Go to dev mode and launch some AI agent
3. Ask it to change the app to your liking (Change UI, etc.)

Bring all online apps to local so you can run privately.

If you have an app or an online service that you use often but want to run locally, simply:

1. Click "create"
2. Enter "a clone of the app at app URL". Feel free to make it as detailed as possible.
3. All projects created inside Pinokio will automatically have a built-in 1-click launcher, so just switch to "run" mode after you finish building.

A Pinokio launcher is made up of 4 types of files (2 of them are auto-generated so you just need to write 2 manually):

1. Config: pinokio.json determines how the project is displayed.
   • automatically generated when a project is created.
2. Environment: ENVIRONMENT stores environment variables to be auto-imported into all scripts in the project.
   • automatically generated when a project is created.
3. Script: the actual script files that can run stuff.
4. Launcher: pinokio.js builds the UI that displays links to the scripts so users can run them with 1-click.

Here's an example file structure for a project named my_project:

~/pinokio
  /api
    /my_project
      pinokio.json      <= config
      ENVIRONMENT       <= environment file
      pinokio.js        <= launcher (may link to start.js, install.js, and update.js)
      start.js          <= script
      install.js        <= script
      update.js         <= script

pinokio.json stores the project information such as title, icon, description, etc., which determines how each project is displayed on Pinokio:

It determines how the project is displayed on Pinokio:

pinokio.json also stores other information such as posts, links, etc. which display links that show up when the project is published:

ENVIRONMENT file stores custom environment variables that get imported into scripts automatically.

Automatically generated when a project is created, and can be edited through the built-in Configure menu:

Projects can have multiple scripts, which are written in json or javascript.

Scripts do NOT run on their own, but either triggered by user interaction (via the launcher) or programmatically (using an API named script.start).

pinokio.js creates a menu UI that lets users launch scripts with 1-click.

Config files are used for storing project metadata. The file name is pinokio.json.

1. The pinokio.json file is automatically generated when you create a new project.
2. You can use the Edit menu in Pinokio to edit the metadata (including uploading the icon file).
3. Or, you can manually edit the pinokio.json file.

A typical config file looks like this:

{
  "title": <title>,
  "description": <description>,
  "icon": <icon>,
  "posts": [
    <x.com url>,
    <x.com url>,
    ...
  }]
  "links": [
    {
      "title": <title>
      "value": <value>
    },
    {
      "title": <title>
      "links": [
        {
          "title": <title>
          "value": <value>
        },
        ...
      ]
    },
    ...
  ]
}

• title: The title to display for the launcher
• description: The description to display for the launcher
• posts: the items in this array will be displayed in the Newsfeed section.
  • <x.com url>: include any x.com post here and they will be rendered in the Newsfeed section.
• links: the items in this array will be displayed in the right sidebar on the info page.
  • <title>: The title of the link
  • <value>: The URL of the link
  • <links>: Create a nested "links" array

The title, description, and icon fields are used to declare how the launcher is displayed.

{
  "title": "Comfyui",
  "description": "The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. https://github.com/comfyanonymous/ComfyUI",
  "icon": "icon.jpeg"
}

The metadata attributes (title, description, icon) determine how the projects are displayed on the home page:

Also the launcher page:

The newsfeed section can be populated simply by adding x.com links to the "posts" array in the pinokio.json file:

{
  "posts": [
    "https://x.com/cocktailpeanut/status/1901791032947450088",
    "https://x.com/cocktailpeanut/status/1901748455418347554",
    "https://x.com/cocktailpeanut/status/1901698217831703023",
    "https://x.com/TheAwakenOne619/status/1901389626931318923",
    "https://x.com/cocktailpeanut/status/1901373187667222923",
    "https://x.com/hasigoki/status/1901296301301731620",
    "https://x.com/cocktailpeanut/status/1901092072263922062",
    "https://x.com/cocktailpeanut/status/1901058105934573799",
    "https://x.com/cocktailpeanut/status/1900995261947932714",
    "https://x.com/cocktailpeanut/status/1901037301989515373",
    "https://x.com/cocktailpeanut/status/1900630168638812243",
    "https://x.com/cocktailpeanut/status/1900603261352374405",
    "https://x.com/cocktailpeanut/status/1900589434153869378",
    "https://x.com/Gun_ther/status/1900363944578990399",
    "https://x.com/napoleon21st/status/1900423646960902614",
    "https://x.com/GorillaRogueGam/status/1900956591530103110",
    "https://x.com/DavidFSWD/status/1901096862352110092",
    "https://x.com/cocktailpeanut/status/1900237861955527161",
    "https://x.com/cocktailpeanut/status/1897017429433442429",
    "https://x.com/dgoldwas/status/1897005272453054671",
    "https://x.com/dgoldwas/status/1896999854418940049",
    "https://x.com/cocktailpeanut/status/1896977467031871632",
    "https://x.com/cocktailpeanut/status/1896968455280349548",
    "https://x.com/lmontoya/status/1896837315634557412",
    "https://x.com/Teslanaut/status/1896837830099468759",
    "https://x.com/deepbeepmeep/status/1896681152024563765",
    "https://x.com/cocktailpeanut/status/1896669569626099988",
    "https://x.com/deepbeepmeep/status/1896264231122772069"
  ]
}

Just by setting the "links" array, you can display as many links as you want:

{
  "links": [{
    "title": "Github",
    "value": "https://github.com/ai-anchorite"
  }]
}

Sometimes you want to add some structure to the links by creating multiple sections. You can simply nest the "links" array inside a "links" array to achieve this:

{
  "links": [{
    "title": "deepbeepmeep (wrote the app)",
    "links": [{
      "title": "X",
      "value": "https://x.com/deepbeepmeep"
    }, {
      "title": "Github",
      "value": "https://github.com/deepbeepmeep"
    }]
  }, {
    "title": "cocktailpeanut (wrote the launcher)",
    "links": [{
      "title": "X",
      "value": "https://x.com/cocktailpeanut"
    }, {
      "title": "Github",
      "value": "https://github.com/cocktailpeanut"
    }, {
      "title": "Discord",
      "value": "https://discord.gg/TQdNwadtE4"
    }]
  }]
}

Often, scripts may require certain environment variables to be set in order to run properly.

Pinokio automatically imports environment variable values from a file named ENVIRONMENT.

The ENVIRONMENT file must follow the unix shell variable format, for example:

S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"

Whenever a script runs, it looks for an ENVIRONMENT file in the root path. If it exists, the stored environment variable values are automatically imported into the environment. Here's an example:

#####################################################################################################################
#
# SD_INSTALL_CHECKPOINT
# - Delete this field if you don't want to auto-download a checkpoint when installing
# - Replace the URL with another checkpoint link if you want a different checkpoint
#
#####################################################################################################################
SD_INSTALL_CHECKPOINT=https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

Then we can use the SD_INSTALL_CHECKPOINT variable in the script via the env variable:

{
  "run": [{
    "method": "fs.download",
    "params": {
      "uri": "{{env.SD_INSTALL_CHECKPOINT}}",
      "dir": "app/models/Stable-diffusion"
    }
  }]
}

You can also edit the contents of the ENVIRONMENT file in the Configure tab:

scripts are the scripts that actually run stuff on your machine. You can write as many scripts as you want, and there is no restriction on the file names.

Run scripts can have 3 attributes:

{
  "version": <schema_version>,
  "run": [
    <step>,
    <step>,
    <step>,
    ...
  ],
  "daemon": <daemon>,
  "env": [
    <prerequisite_env>,
    <prerequisite_env>,
    ...
  ]
}

• <schema_version>: script schema version (current version is 4.0)
• <step>: The run array contains multiple <step> items. Each <step> is executed one by one, with each step passing down its return value to the next step.
• <daemon>: whether to keep the script running after all <step> items have finished executing. For example, when you have a script that starts a web server, if you do not set "daemon": true, the script will terminate and kill the server at the end. Required for all apps that needs to keep running. Not needed for one off apps that run and return immediately.
• <prerequisite_env>: prerequisite environment variable declaration. A lot of apps require setting some environment variables (such as OPENAI_API_KEY) before running. The <prerequisite_env> declaration lets you declare the environment variables that need to be set before running a script.
  • When this is set, the script automatically displays a form before running a script, allowing the user to enter the corresponding environment variable value.

The script lifecycle is very simple:

{
  "env": [
    <prerequisite_env>,
    <prerequisite_env>,
    ...
  ],
  "run": [
    <RPC>,
    <RPC>,
    <RPC>,
    <RPC>,
    <RPC>,
    ...
  ]
}

1. The env array is optional. Only required for scripts that require setting some environment variables before running. When this is set, Pinokio automatically displays a form (if the specified environment variables are not already set) to let the user enter the values, which then gets stored in a file named ENVIRONMENT. Once this is set, next time the script runs, it will reference the ENVIRONMENT file to automatically use the environment variable value.
2. The run array is an ordered list of RPC calls.
3. Pinokio walks through the run array to run the steps one by one.
4. Each <RPC> is freshly decoded with the template interpreter before executing.
5. After each step, the return value of each step is passed down to the next step in the form of input.
6. Each step can make use of the input variable passed in from the previous step in their template expression to dynamically construct the method to run.
7. When it reaches the end of the run array, the script halts, and all the processes associated with the script is garbage collected.

A lot of apps require you setting some environment variable values such as OPENAI_API_KEY, before running.

With Pinokio, you do not need to manually specify the environment variables every time you run these apps thanks to the ENVIRONMENT file.

Every pinokio project has a file named ENVIRONMENT which stores environment variable values. Wheenver script files are run, the values in the ENVIRONMENT file are imported automatically.

Instead of the user manually visiting the Configure tab to edit the environment variables, a script may EXPLICITLY display a form to let users set the environment variables before starting.

This can be achieved using the env array.

1. If the environment variables are already set in the ENVIRONMENT file, it will just use those variables to start automatically without pausing.
2. If the environment variables are NOT yet set, it will NOT start the script, but display a form that needs to be filled out. Once the user submits the form, the values get stored into ENVIRONMENT, and then the script processing starts, using the newly set e environment variables.

To achieve this, you can attach a env array in a script.

{
  "env": [<requiremd_env>, <required_env>, ...],
  "run": [
    ...
  ]
}

where <required_env> is an object that describes the required environment variables:

<required_env> := {
  key: <environment_variable_name>,
  title: <title>,
  description: <description>,
  default: <default_value>,
  host: <key_host>,
}

• <environment_variable_name>: The name of the environment variable needed to start the script.
• <title>: (optional) A simple title for the field
• <description>: (optional) description for the field
• <default>: (optional) a default value that will be pre-filled when the form is rendered.
• <key_host>: (optional) hostname for fetching the default value from the shared key storage

For example, let's say our script looks like the following:

{
  "env": [{
    "key": "OPENAI_API_KEY"
  }],
  "run": [
    {
      "method": "shell.run",
      "params": {
        "venv": "venv",
        "message": "python app.py", 
      }
    }
  ]
}

When the user runs this script for the first time, the OPENAI_API_KEY environment variable won't be filled out, therefore will be prompted with you will be prompted with a form to fill out the OPENAI_API_KEY environment variable:

When the user submits the form, the submitted value will be stored inside the ENVIRONMENT file.

Then from the next time the script runs, it will automatically import the OPENAI_API_KEY environment variable from the ENVIRONMENT file instead of displaying the form.

You can add more details to the form fields using attributes like title and description:

{
  "env": [{
    "title": "openai api key",
    "description": "enter your openai api key. you can get it at https://platform.openai.com/api-keys",
    "key": "OPENAI_API_KEY"
  }, {
    "title": "huggingface token",
    "description": "enter your huggignface token. you can get it at https://huggingface.co/settings/tokens",
    "key": "HF_TOKEN"
  }],
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": "venv",
      "message": "python app.py"
    }
  }]
}

The resulting form fields will display more details:

You can program the form to launch with a default value filled in, using the default attribute:

{
  "env": [{
    "title": "OPENAI API Key",
    "description": "OPENAI API KEY https://platform.openai.com/api-keys",
    "key": "OPENAI_API_KEY",
    "default": "THIS_IS_A_FAKE_API_KEY"
  }],
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": "venv",
      "message": "python app.py"
    }
  }]
}

Here the script sets the default to THIS_IS_A_FAKE_API_KEY. You can see it below:

NOTE

The default value is NOT saved to the ENVIRONMENT file until the user submits the form. It's literally just a default value to display when the form shows up.

Autofilling is great but it's not very powerful if you can only autofill fixed values.

What if there was an autofill feature that works just like how web browsers autofills passwords for every website using its private key storage?

This is where the key store comes in. and you can trigger it simply by including the host attribute (a website hostname). Here's an example:

{
  "env": [
    {
      "key": "OPENAI_API_KEY",
      "host": "openai.com"
    },
    {
      "key": "HF_TOKEN",
      "host": "huggingface.co"
    }
  ],
  "run": [
    {
      "method": "shell.run",
      "params": {
        "venv": "venv",
        "message": "python app.py"
      }
    }
  ]
}

Note that each env item now has a host attribute.

Just like how browser password managers store passwords tied to a web domain, Pinokio autofill lets you save keys under each host.

When the user submits the above form, two things will happen:

The OPENAI_API_KEY and HF_TOKEN environment variables will be stored into the ENVIRONMENT file in the project folder.

The key storage (located at $PINOKIO_HOME/key.json) will store the submitted values as follows:

{
  "openai.com": [
    "sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  ],
  "huggingface.co": [
    "hf_SKXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  ]
}

1. Note that the keys are stored under an array.
2. This is because keys can have multiple values

Once the environment variables are stored, the same script will skip the env step and go straight to running the script instructions next time it's run.

If you wish to edit the ENVIRONMENT file, you can easily do so in the Configure tab.

Now here comes the true power of shared key store autofill---when you have another project (without the ENVIRONMENT set) that references the hosts (openai.com or huggingface.co), the fields will be autofilled by loading from the shared key storage.

Let's say there's another project that includes a script that looks like this:

{
  "env": [
    {
      "key": "OPENAI_API_KEY",
      "host": "openai.com"
    },
    {
      "key": "HF_TOKEN",
      "host": "huggingface.co"
    }
  ],
  "run": [
    {
      "method": "shell.run",
      "params": {
        "message": "python different_app.py"
      }
    }
  ]
}

Since this is a completely different project, the ENVIRONMENT file need to be set again when the user runs it for the first time. When it's run for the first time, the user will get the following form, with the OPENAI_API_KEY and HF_TOKEN fields autofilled (by looking up the $PINOKIO_HOME/key.json file:

A script is made up of one or more instructions.

1. Walks through the script run array one by one while keeping a state machine.
2. For each instruction, interprets the dynamic instruction (templates) using the state machine.
3. After the instruction is interpreted, it is executed.

Here's an example script:

{
  "run": [
    {
      "method": "jump",
      "params": {
        "id": "{{gpu === 'nvidia' ? 'cuda' : 'cpu'}}"
      }
    },
    {
      "id": "cpu",
      "method": "shell.run",
      "params": {
        "message": "pip install torch torchvision torchaudio"
      }
    },
    {
      "id": "cuda",
      "method": "shell.run",
      "params": {
        "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
      }
    }
  ]
}

This script is made up of 3 instructions:

Instruction 1:

{
  "method": "jump",
  "params": {
    "id": "{{gpu === 'nvidia' ? 'cuda' : 'cpu'}}"
  }
}

Instruction 2:

{
  "id": "cpu",
  "method": "shell.run",
  "params": {
    "message": "pip install torch torchvision torchaudio"
  }
}

Instruction 3:

{
  "id": "cuda",
  "method": "shell.run",
  "params": {
    "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
  }
}

An instruction is a modified version of JSON-RPC.

{
  "id": <RPC_id>,
  "when": <RPC_condition>,
  "method": <RPC_method>,
  "params": <RPC_params>,
  "next": <RPC_next>
}

1. <RPC_id>: optional. mark this RPC call with the id of <RPC_id>. a jump RPC call can jump to any step within the run array.
2. <RPC_condition>: optional. if evaluated to true, run this step. Otherwise go to the next step.
3. <RPC_method>: The RPC method to call
4. <RPC_params>: A JSON parameter to pass to the <RPC_method> as payload. The <RPC_params> object will be available as the value {{input}} template expression on the next step.
5. <RPC_next>: optional. The id or index of the next instruction to jump to. If not specified, moves on to the next instruction in the run array.

To learn about all the available RPC APIs, see the script section.

The id attribute can be used to mark an instruction, so it can be referenced from the other parts of the script. More specifically, you can use the jump API to jump to the id.

{
  "run": [{
    "method": "jump",
    "params": {
      "id": "{{gpu === 'nvidia' ? 'cuda' : 'cpu'}}"
    }
  }, {
    "id": "cpu",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio"
    }
  }, {
    "id": "cuda",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
    }
  }]
}

In above example, when the script starts running it encounters a jump.

1. If the gpu === 'nvidia', it jumps to the instruction marked as cuda (the third instruction in the run array)
2. If otherwise, it jumps to the instruction marked as cpu (the second instruction in the run array)

The when attribute can be used to conditionally run instructions (or skip) depending on the condition.

{
  "run": [{
    "when": "{{gpu !== 'nvidia'}}",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio"
    }
  }, {
    "when": "{{gpu === 'nvidia'}}",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
    }
  }]
}

• run[0] is run if the gpu is NOT nvidia. (In nvidia GPU machines, this step is ignored and goes to the next step immediately)
• run[1] is run if the gpu is nvidia.

You can use one of many system API methods to run things.

Learn more here: API.

Also, for more advanced usage, you may implement your own custom method implementation using a JavaScript function.

Learn more about custom instructions here: Custom Instruction

Parameters that get passed to the method specified by the method attribute (only for the system API, not required for custom JavaScript instructions).

While you can write a separate jump instruction to jump to instructions, often you may want to jump without creating a separate instruction.

For example you may want to jump to an instruction after executing the current execution. This is where the next attribute comes in.

The next attribute can take the following values:

1. id: if an id is specified, and an instruction with the id exists in the same script, it jumps to that location after the current instruction.
2. index: jumps to the run[index] instruction after running the current instruction.
3. null: jumps to the end where the script ends.

Here's an example:

{
  "run": [
    {
      "when": "{{gpu === 'nvidia'}}",
      "method": "shell.run",
      "params": {
        "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
      },
      "next": "install"
    },
    {
      "when": "{{platform === 'darwin'}}",
      "method": "shell.run",
      "params": {
        "message": "pip install torch torchvision torchaudio"
      },
      "next": "install"
    },
    {
      "method": "notify",
      "params": {
        "html": "Exception handling"
      },
      "next": null
    },
    {
      "id": "install",
      "method": "script.start",
      "params": {
        "uri": "install.js"
      }
    }
  ]
}

1. The first instruction (run[0]) jumps to install after execution, which calls script.start to launch install.js
2. The second instruction (run[1]) also jumps to install after execution, which calls script.start to launch install.js
3. If none of the above two instructions are executed, the notify API is executed, and then jumps to null, which halts the script WITHOUT running the install.js.

Being able to run things is great, but if the commands were static, it would not be powerful.

Fortunately, Pinokio has a dynamic interpreter that runs commands using the memory.

1. Templates: Anything wrapped in {{ }} will be dynamically filled out for each step, using the script memory.
2. State Machine: As a script gets executed, a state machine keeps track of the script memory, filling in the templates right before each instruction is about to run.

Here's an example of using system variables to run different commands depending on the platform (using the platform variable)

{
  "run": [
    {
      "method": "shell.run",
      "params": {
        "message": "python app.py --port {{port}}"
      }
    }
  ]
}

This is a script made up of a single step shell.run, where we can see the template expression {{port}}.

The port variable returns the next available system port. In this case let's assume it returns 42003.

After interpretion it results in something like:

{
  "method": "shell.run",
  "params": {
    "message": "python app.py --port 42003"
  }
}

This command then runs python app.py --port 42003. The running phase will be explained in the next section.

The template expressions are instantiated freshly at the beginning of every step in the run array, using the up-to-date memory variables available at the time of parsing.

For example let's say we have a logging script:

{
  "run": [{
    "method": "log",
    "params": {
      "raw": "running instruction {{current}}"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "running instruction {{current}}"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "running instruction {{current}}"
    }
  }]
}

Since the current variable returns the index of the currently executing step in the run array,

1. First it will run the run[0] step, and print running instruction 0
2. Then it will run the next step run[1], and print running instruction 1
3. Finally it will run the final step run[2], and print running instruction 2

Once each step has been instantiated (from the interpet phase), the result is passed to the JSON-RPC processor to actually run the step.

Here's an example script with 3 steps:

{
  "run": [{
    "method": "jump",
    "params": {
      "id": "{{gpu === 'nvidia' ? 'cuda' : 'cpu'}}"
    }
  }, {
    "id": "cpu",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio"
    }
  }, {
    "id": "cuda",
    "method": "shell.run",
    "params": {
      "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
    }
  }]
}

Here's the step 1:

{
  "method": "jump",
  "params": {
    "id": "{{gpu === 'nvidia' ? 'cuda' : 'cpu'}}"
  }
}

Let's say the gpu is NVIDIA. Then the instantiated JSON-RPC object will be:

{
  "method": "jump",
  "params": {
    "id": "cuda"
  }
}

This calls the jump API method, which jumps to the step labled as "id": "cuda", which is step 3:

{
  "id": "cuda",
  "method": "shell.run",
  "params": {
    "message": "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121"
  }
}

Here, it runs the shell.run API method, which starts a new shell and runs the command specified in the message attribute (pip install ...)

After the final step is run, the script finishes.

When a Pinokio script finishes running, every shell session that was spawned through the script gets disposed of, and all the related processes get shut down.

For example, let's try launching a local web server using http-server. Create a new folder named httpserver under the Pinokio api folder, and create a new script named index.json:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "npx -y http-server"
    }
  }]
}

Then go back to Pinokio and you'll see this app show up on the home page. Click through and click the index.json tab on the sidebar, and it will start this script, which should launch the web server using npx http-server.

But the problem is, right after it launches the server it will immediately shut down and you won't be able to use the web server.

This is because Pinokio automatically shuts down all processes associated with the script when it finishes running all the steps in the run array.

To avoid this, you need to tell Pinokio this app should stay up even after all the steps have run. We simply need to add a daemon attribute:

{
  "daemon": true,
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "npx -y http-server"
    }
  }]
}

Now retry starting the script, and you'll see that the web server starts running and does not shut down.

The web server will serve all the files in the current folder (in this case just index.json), like this:

You can stop the script by pressing the "stop" button at the top of the page.

Learn more about daemon mode here

You can also write JavaScript files to implement a script. The benefits of writing in Javascript are:

1. You have access to all node.js APIs
2. Dynamically construct the scriptusing node.js APIs
3. Can write custom instructions

Simply export the same JSON script, but written in JavaScript. Exactly the same except it's stored as a .js file.

// start.js
module.exports = {
  "run": [
    {
      "method": "shell.run",
      "params": {
        "message": "git clone https://huggingface.co/spaces/cocktailpeanut/BRIA-RMBG-1.4 app"
      }
    },
    {
      "method": "shell.run",
      "params": {
        "venv": "env",
        "path": "app",
        "message": "pip install -r requirements.txt"
      }
    },
  ]
}

The previous section discussed some of the built-in API methods available out of the box.

But you can even write your own custom JavaScript method that can be called using the same JSON-RPC syntax.

There are 2 ways to implement custom script methods:

1. Inline Method: (recommended) This is the easiest way to get started. You can directly include a javascript function as a step inline.
2. Plugin Method: You can also write a separate JavaScript file to declare an API class and call it.

Instead of the JSON-RPC syntax (method, params, next, etc.) you can specify a single method JavaScript async function.

The best part is, it can blend into the rest of the JSON-RPC API calls naturally.

module.exports = {
  run: [
    STEP1,
    STEP2,
    ...,
    {
      method: async (req, ondata, kernel) => {
        // do whatever you want. here. you have full access to
        // 1. ANY JavaScript method
        // 2. ANY kernel API call (via `kernel`)
        // 3. The terminal (Just call `ondata({ raw: <message> })` to print any message on the executing terminal.
        // 4. request object (includes attributes such as req.cwd, req.input, etc.)
        return response
      }
    },
    STEPN,
    ...
  }]
}

Arguments

1. req: Request object
   • cwd: The current execution path
   • current: The current step index (If it's the 3rd step, it will return 2)
   • total: The total number of steps in this script (If there are 4 steps, it will be 4)
   • input: If the previous step has a return value, it should be accessible via input.
   • args: If the parent script file was launched with params, the params will be available as args throughout ALL steps in the script execution.
   • next: The next step to run
   • parent: The paret JavaScript file info
     • path: The script file path (example: /Users/x/pinokio/api/test/custom/inline.js)
2. ondata: Can be used to print messages to the terminal by calling ondata({ raw: message })
3. kernel:
   • platform: darwin, win32, or linux`
   • arch: architecture (arm64, etc.)
   • envs: a key/value pair object that contains ALL environment variable values
   • homedir: The pinokio home path
   • exec(): A JavaScript interfact to execute shell commands. You can even print to the user facing terminal.

Here's an example:

const fs = require('fs')
const path = require('path')
module.exports = {
  run: [
    {
      method: "input",
      params: {
        title: "Command Launcher",
        form: [{
          title: "Enter the launch command",
          key: "start"
        }]
      }
    },
    {
      method: async (req, ondata, kernel) => {
        // copy some template files into the execution folder (req.cwd)
        await fs.promises.cp(path.resolve(__dirname, "template"), req.cwd, { recursive: true })

        // write a start.json file into the execution folder (req.cwd) using the `req.input.start` value from the previous step.
        await fs.promises.writeFile(path.resolve(req.cwd, "start.json"), JSON.stringify({
          run: [{
            method: "shell.run",
            params: {
              input: true,
              message: req.input.start
            }
          }]
        }, null, 2))

        // you can even run some commands in the terminal using the `kernel.exec` API
        await kernel.exec({
          message: [
            "git init",
            "git add .",
            "git commit -am init"
          ],
          path: req.cwd
        }, (e) => {
          ondata(e)
        })
        return {
          filepath: path.resolve(req.cwd, "start.json")
        }
      },
    },
    {
      method: "notify",
      params: {
        text: "File written to {{input.filepath}}"
      }
    }
  ]
}

1. First, it calls the input JSON-RPC API to take the user input under the key start
2. Then this value is passed to the next step as req.input.
3. Note that the second step is the method async JavaScript function, which takes 3 arguments (req, ondata, kernel), where the req.input.start contains the user input from the previous step.

Unlike the Inline method where the custom JavaScript method is included inline as one of the steps, the plugin method lets you:

1. Write a separate JavaScript file to declare the behavior
2. And call the JavaScript file using a JSON-RPC syntax.
3. The main script can be written in pure JSON.

It is more complex, but the benefit is you can keep all the raw JavaScript functions as separate files, while keeping the actual script purely JSON based.

The JavaScript file is where all the logic is written. It must follow the following convention:

// api.js
// The class name can be anything, it doesn't matter
const fs = require('fs')
class API {
  // req: the request object, where the request.params contains the arguments passed in from an external script
  // ondata: can be used to print to the terminal
  // kernel: direct access to the kernel
  async custom_method(req, ondata, kernel) => {
    // Do stuff here. Here's an example
    let res = await fetch(req.params.url).then((res) => {
      return res.json()
    })
    await fs.promises.writeFile("result.json", JSON.stringify(res))
  }
}
module.exports = API

Now that we've written the logic, we can call it from any Pinokio script. The syntax is the same JSON-RPC syntax.

{
  "method": <method_name>,
  "uri": <file_path>,
  "params": <params>
}

The difference in this case is, we have an additional uri attribute.

• <method_name>: The method name to call
• <file_path>: THe file path that contains the API class
• <params>: The parameters to pass into the API class via req.params`

For example, to call the custom_method() method in the API class above, we can do:

{
  "run": [{
    "uri": "api.js",
    "method": "custom_method",
    "params": {
      "url": "https://jsonplaceholder.typicode.com/todos/1"
    }
  }]
}

This will call the custom_method() of the API class inside the api.js file.

It will pass in https://jsonplaceholder.typicode.com/todos/1 through the params, so the req.params.url will be https://jsonplaceholder.typicode.com/todos/1.

First write a JavaScript class file:

// plugin.js
class Plugin {
  async my_method (req, ondata, kernel) {
    ondata({ raw: `\r\nInput Command was ${req.input.start}\r\n` })
  }
}
module.exports = Plugin

Next, you can call this script from a JSON script:

{
  "run": [{
    "method": "input",
    "params": {
      "title": "Command Launcher",
      "form": [{
        "title": "Enter the launch command",
        "key": "start"
      }]
    }
  }, {
    "uri": "plugin.js",
    "method": "my_method",
    "params": {
      "launch_command": "{{input.start}}"
    }
  }]
}

Let's say you want to write an API that accepts a URL and opens that URL in a browser automatically.

We can use the kernel.playwright variable to use the Playwright that is included in Pinokio kernel. Let's create a browser.js file:

// browser.js
class Browser {
  async open(req, ondata, kernel) {
    let { firefox } = kernel.playwright
    const browser = await firefox.launch({ headless: false, });
    const context = await browser.newContext({ viewport: null })
    const page = await context.newPage()
    await page.goto(req.params.url)
  }
}
module.exports = Browser

Now we can call this from a script:

{
  "run": [{
    "uri": "browser.js",
    "method": "open",
    "params": {
      "url": "https://pinokio.computer"
    }
  }]
}

This will pass in req.params.url as https://pinokio.computer into the open() method in the browser.js class, which automatically launches a firefox browser and navigates to the req.params.url URL.

A launcher script lets you describe a launcher UI. The launcher is the sidebar menu that may let the user:

1. Run scripts
2. Start instant shells
3. Open any web url in a tab

Each project can have at most 1 launcher file, which describes how the launcher works.

To implement a launcher, you must create a file named pinokio.js at the root of your project.

Building a UI requires only a single file named pinokio.js. Simply place a file named pinokio.js in the project root folder.

module.exports = {
  "version": <script_schema_version>,
  "pre": <pre>,
  "menu": <menu>,
}

• <script_schema_version>: The schema version used (the latest version is "4.0")
• <pre>: (optional) Prerequisites. In case the script requires installation of 3rd party programs that cannot be easily installed through the script, you may specify a pre array to provide download links to the user before the installation starts. Each item in the pre array may have the following attributes:
  • text: The text to display for the item.
  • icon: The icon file path to display for the item.
  • href: The URL to open.
  • fs: open the file in a file explorer or the default app.
    • if set to "open", opens the file
    • if set to "view", opens in file explorer
    • if set to true, same as "view". opens in file explorer.
• <menu>: An array of tab items, or an async function that takes kernel and info as arguments and returns the same tab items array. Each item in the array may have the following attributes:
  • text: The text to display on the tab.
  • icon: The fontawesome class name to display for the tab---Use the built-in fontawesome class (example: "fa-solid fa-house").
  • image: image path to display for the tab (You can use either the icon or the image, but if you use the image attribute, you should also include the image file at the specified path).
  • href: The URL to open in the tab.
  • params (optional): The query parameters to pass to the tab.
    • If passed to a script, the params will be made available as the input variable inside the first step of the run script.
  • shell (optional): Start an instant shell.
  • popout (optional): Opens the href link in an external browser instead of Pinokio if set to true
  • menu (optional): If specified, creates a nested menu. The nested menu follows the same specification as the top level menu (with text, icon, href, params, and popout attributes)
  • default (optional): If specified, this tab item is automatically selected by default. When the href attribute is a script URL, the selection also means the script will be automatically started. This can be used to implement automatically executing scripts.

Use the pre array to implement

Let's say an app needs Ollama to run.

We can direct the user to install Ollama before installing the app, using the <pre> syntax in pinokio.js:

module.exports = {
  version: "2.0",
  title: "LLM App",
  pre: [{
    icon: "ollama.png",
    title: "Ollama",
    description: "Get up and running with large language models.",
    href: "https://ollama.com/"
  }],
  ...
}

When this is downloaded, the user will be shown the following Prerequisites screen BEFORE the install screen:

Use the menu array to implement

Here's a UI script for generating a minimal launcher UI:

module.exports = {
  version: "2.0",
  title: "Test Launcher",
  description: "This is for testing a test launcher",
  icon: "icon.png",
  menu: [{
    icon: "fa-brands fa-google",  // see https://fontawesome.com/icons/google?f=brands&s=solid
    text: "Open Google",
    href: "https://google.com",
  }, {
    icon: "fa-brands fa-discord",
    text: "Open Discord in New Window",
    href: "https://discord.gg/TQdNwadtE4",
    popout: true    // "popout": true => opens the link in an external browser instead of as a Pinokio tab.
  }]
}

Each menu item is interactive---when the user clicks on it, it can trigger one of the following actions:

1. href: Open a URL or a script in a new tab
2. script: Start an instant shell
3. run: Run a one-off command

The href attribute opens a new tab.

If the URI is a local file path to a script, it will start the script execution terminal:

{
  "menu": [{
    "icon": "fa-solid fa-check",
    "text": "Start",
    "href": "start.json"
  }]
}

If the URI is an http/https url it will open a new web window loading the URL:

{
  "menu": [{
    "icon": "fa-solid fa-check",
    "text": "Web UI",
    "href": "http://localhost:3000"
  }]
}

Start an instant shell in a new tab.

{
  "menu": [{
    "icon": "fa-solid fa-rocket",
    "text": "Launch a web server",
    "shell": {
      "message": "npx -y http-server"
    }
  }]
}

The shell syntax is a subset of the attributes available in the shell.run API:

{
  "shell": {
    "input": <input>,
    "message": <message>,
    "path": <path>,
    "env": <env>,
    "venv": <venv_path>,
    "conda": <conda_config>,
  }
}

• <input>: (optional) Whether the shell is interactive or not (whether the user can enter keystrokes into the shell)
  • when true: the shell launches in input mode. The user can enter keys. Useful for launching CLI Apps that require user interaction.
  • when false (or not specified): the shell launches in non-interactive mode. Useful for automated shell execution that should not allow user interaction.
• <message>: The message to enter into the shell. May be a string (Different from shell.run in that it can only have one message).
  • string => enters the message.
• <path> (optional): The path from which to start the shell session (can be either a relative or absolute path).
  • When NOT specified: the shell starts from the same path as the currently running script.
  • When specified: the shell session starts from the specified path
• <env> (optional): Environment variable key/value pairs.
  • when the key/value pairs are specified, the custom environment values are set.
  • when NOT specified, the shell uses the default environment
• <venv_path> (optional): A declarative syntax for automatically creating or activating a venv environment at the specified path.
  • When NOT specified (default): Does not create or activate a venv and runs the shell session normally.
  • When specified: Creates a venv at the specified path if it doesn't exist yet, or if it exists, activates the existing venv at the specified path, and runs the shell session in that venv.
  • the shell automatically creates a venv environment at that path if it doesn't exist, then automatically activates the environment before running the command(s) specified by the message attribute.
• <conda_config> (optional): Declarative syntax for defining the conda environment that will be activated for this shell session. Can be an object or a string.

  • When NOT specified (default): By default Pinokio installs a handful of essential modules in the base conda environment that's isolated to Pinokio (Even if you have a conda installed on your system globally, Pinokio will NOT use it and use the isolated conda built-into Pinokio).

  • When specified: The <conda_config> attribute can be a string or an object.

    • string: the <conda_config> is interpreted as the path in which the conda environment is stored. (Ex: if "conda": "conda_env", the shell will activate the conda environment at the conda_env path).
    • object: In some cases you may want more advanced ways of creating/activating the conda environments declaratively. When the `<conda_config> is an object type instead of string, the following rules apply:
      • path: Same as when the <conda_config> is a string. Interpreted as the path in which the conda environment is stored. (Ex: if "conda": "conda_env", the shell will activate the conda environment at the conda_env path).
      • name: the conda environment name to activate. Unlike activation by path, the environments created/activated this way are centrally stored under the PINOKIO_HOME/bin/miniconda folder.
      • skip: if set to true, do NOT activate ANY environment (By default this is set to false, and therefore every shell activates the Pinokio-global base conda environment every time unless you specify with the params.conda attribute.
      • python: The python version to install inside the environment (The default is python=3.10 if not specified)

  • the shell automatically creates a conda enviornment at that path if it doesn't exist, then automatically activates the environment before running the command(s) specified by the message attribute.

Run a one-off command.

{
  "menu": [{
    "icon": "fa-solid fa-rocket",
    "text": "Open pinokio.js in cursor",
    "run": "cursor pinokio.js"
  }]
}

If you're trying to run a command that does NOT terminate (such as starting a web server), do NOT use run, but start a shell using the shell attribute instead.

The sidebar menu is automatically re-rendered every time a step in the currently running script finishes.

This means you can write the pinokio.js file so it automatically displays relevant items in realtime.

For example, when the app is running, you may want to display a link to open the actual web UI. Or when the app is not running, you may want to display a "Start" button instead.

We can achieve this type of dynamic menu rendering by using a function instead of array. Instead of setting a static menu array, set the menu as an async function that takes kernel and info as an arguments.

You can use the info variable to get various types of status information about the files and scripts:

• info.local(filepath): get the local variable object of a script running at filepath.
• info.running(filepath): get the running status of a script at filepath.
• info.exists(filepath): check if a file exists at filepath.
• info.path(filepath): get the absolute path of a fileapth.

Check out an example below, where it makes use of the info API to determine whether install.json or start.json scripts are running, and if they are, get the local variable in memory, etc.

const path = require("path")
module.exports = {
  version: "2.0",
  title: "InvokeAI",
  description: "Generative AI for Professional Creatives",
  icon: "icon.jpeg",
  menu: async (kernel, info) => {
    /**********************************************************************************************
      info has 4 methods (where `filepath` may be a relative path or an absolute path.):
        - info.local(filepath): get the local variable object of a script running at `filepath`.
        - info.running(filepath): get the running status of a script at `filepath`.
        - info.exists(filepath): check if a file exists at `filepath`.
        - info.path(filepath): get the absolute path of a `fileapth`.
    **********************************************************************************************/
    let installing = info.running("install.json")
    let installing = info.running("install.json")
    let installed = info.exists("app/env")
    if (installing) {
      return [{ icon: "fa-solid fa-plug", text: "Installing...", href: "install.json" }]
    } else if (installed) {
      let running = info.running("start.json")
      if (running) {
        let memory = info.local("start.json")
        if (memory && memory.url) {
          return [
            { icon: "fa-solid fa-rocket", text: "Web UI", href: memory.url },
            { icon: "fa-solid fa-terminal", text: "Terminal", href: "start.json" },
            { icon: "fa-solid fa-rotate", text: "Update", href: "update.json" },
          ]
        } else {
          return [
            { icon: "fa-solid fa-terminal", text: "Terminal", href: "start.json" },
            { icon: "fa-solid fa-rotate", text: "Update", href: "update.json" },
          ]
        }
      } else {
        return [{
          icon: "fa-solid fa-power-off",
          text: "Start",
          href: "start.json",
        }, {
          icon: "fa-solid fa-rotate", text: "Update", href: "update.json"
        }, {
          icon: "fa-solid fa-plug", text: "Reinstall", href: "install.json"
        }, {
          icon: "fa-solid fa-broom", text: "Factory Reset", href: "reset.json"
        }]
      }
    } else {
      return [
        { icon: "fa-solid fa-plug", text: "Install", href: "install.json" },
        { icon: "fa-solid fa-rotate", text: "Update", href: "update.json" }
      ]
    }
  }
}

Based on the determined app status, the dynamic menu function can generate menu items.

1. check whether a file/folder exists at a path: info.exists()
2. check if a script at a specified path is running: info.running()
3. get the local variables object for a script at specified path: info.local()

You can nest the menu array into another menu (up to level 2)

module.exports = {
  title: "Test Launcher",
  description: "This is for testing a test launcher",
  icon: "icon.png",
  menu: [{
    icon: "fa-solid fa-download",
    text: "Download Models",
    menu: [
      { text: "Download by URL", icon: "fa-solid fa-download", href: "download.html?raw=true" },
      { text: "SDXL", icon: "fa-solid fa-download", href: "download-sdxl.json", mode: "refresh" },
      { text: "SDXL Turbo", icon: "fa-solid fa-download", href: "download-turbo.json", mode: "refresh" },
      { text: "Stable Video XT", icon: "fa-solid fa-download", href: "download-svd-xt.json", mode: "refresh" },
      { text: "Stable Video", icon: "fa-solid fa-download", href: "download-svd.json", mode: "refresh" },
      { text: "Stable Video XT 1.1", icon: "fa-solid fa-download", href: "download-svd-xt-1.1.json", mode: "refresh" },
      { text: "LCM LoRA", icon: "fa-solid fa-download", href: "download-lcm-lora.json", mode: "refresh" },
      { text: "SD 1.5", icon: "fa-solid fa-download", href: "download-sd15.json", mode: "refresh" },
      { text: "SD 2.1", icon: "fa-solid fa-download", href: "download-sd21.json", mode: "refresh" },
      { text: "Playground2.5 fp16", icon: "fa-solid fa-download", href: "download-playground-fp16.json", mode: "refresh" },
      { text: "Playground2.5", icon: "fa-solid fa-download", href: "download-playground.json", mode: "refresh" },

    ]
  }]
}

Using the default attribute, it is possible to implement auto-executing scripts.

For example, let's say we want the following behavior:

• run install.js if app/env does not exist.
• run start.js if app/env exists, and start.js is not already running.

module.exports = {
  title: "Auto Launcher",
  icon: "icon.png",
  menu: async (kernel, info) => {
    if (info.exists("app/env")) {
      // already installed. select the "start.js", automatically running `start.js`
      return [{
        text: "Install",
        href: "install.js"
      }, {
        default: true,
        text: "Start",
        href: "start.js"
      }]
    } else {
      // not installed yet. select the install.js tab.
      return [{
        default: true,
        text: "Install",
        href: "install.js"
      }, {
        text: "Start",
        href: "start.js"
      }]
    }
  }
}

Pinokio script is a declarative markup that can shell commands, work with files, make network requests, and pretty much everything you need to automatically install and run ANYTHING on a computer.

It is written in JSON, and can also be written in JavaScript (which returns the resulting JSON) in case you need to make them dynamically change.

• shell.run

The shell.run command starts an instant shell, runs the specified commands, and closes the shell.

{
  "method": "shell.run",
  "params": {
    "input": <input>,
    "message": <message>,
    "path": <path>,
    "env": <env>,
    "venv": <venv_path>,
    "conda": <conda_config>,
    "on": <shell_event_handler>,
    "sudo": <sudo>,
    "cache": <cache>
  }
}

• <input>: (optional) Whether the shell is interactive or not (whether the user can enter keystrokes into the shell)
  • when true: the shell launches in input mode. The user can enter keys. Useful for launching CLI Apps that require user interaction.
  • when false (or not specified): the shell launches in non-interactive mode. Useful for automated shell execution that should not allow user interaction.
• <message>: The message to enter into the shell. May be a string, or an array.
  • string => enters the message.
  • array => enters the messages in the array sequentially.
    • For example "message": ["pip install -r requirements.txt", "pip install torch"] will internally run: pip install -r requirements.txt && pip install torch
• <path> (optional): The path from which to start the shell session (can be either a relative or absolute path).
  • When NOT specified: the shell starts from the same path as the currently running script.
  • When specified: the shell session starts from the specified path
• <env> (optional): Environment variable key/value pairs.
  • when the key/value pairs are specified, the custom environment values are set.
  • when NOT specified, the shell uses the default environment
• <venv_path> (optional): A declarative syntax for automatically creating or activating a venv environment at the specified path.
  • When NOT specified (default): Does not create or activate a venv and runs the shell session normally.
  • When specified: Creates a venv at the specified path if it doesn't exist yet, or if it exists, activates the existing venv at the specified path, and runs the shell session in that venv.
  • the shell automatically creates a venv environment at that path if it doesn't exist, then automatically activates the environment before running the command(s) specified by the message attribute.
• <conda_config> (optional): Declarative syntax for defining the conda environment that will be activated for this shell session. Can be an object or a string.

  • When NOT specified (default): By default Pinokio installs a handful of essential modules in the base conda environment that's isolated to Pinokio (Even if you have a conda installed on your system globally, Pinokio will NOT use it and use the isolated conda built-into Pinokio).

  • When specified: The <conda_config> attribute can be a string or an object.

    • string: the <conda_config> is interpreted as the path in which the conda environment is stored. (Ex: if "conda": "conda_env", the shell will activate the conda environment at the conda_env path).
    • object: In some cases you may want more advanced ways of creating/activating the conda environments declaratively. When the `<conda_config> is an object type instead of string, the following rules apply:
      • path: Same as when the <conda_config> is a string. Interpreted as the path in which the conda environment is stored. (Ex: if "conda": "conda_env", the shell will activate the conda environment at the conda_env path).
      • name: the conda environment name to activate. Unlike activation by path, the environments created/activated this way are centrally stored under the PINOKIO_HOME/bin/miniconda folder.
      • skip: if set to true, do NOT activate ANY environment (By default this is set to false, and therefore every shell activates the Pinokio-global base conda environment every time unless you specify with the params.conda attribute.
      • python: The python version to install inside the environment (The default is python=3.10 if not specified)

  • the shell automatically creates a conda enviornment at that path if it doesn't exist, then automatically activates the environment before running the command(s) specified by the message attribute.

• <shell_event_handler> (optional): event handler for the shell. Can be used to parse the terminal when running shell.run. The parsed result can be passed down to the next API call in the run array as the input variable.
  • if specified: The shell keeps running until the specified pattern is met.
    • You may have multiple items in the <shell_event_handler> array. The first event to match will handle the event and move to the next step. An event handler object may have the following attributes:
      • event: a regular expression string to match.
      • kill, done, or break: describe the behavior for when the event match happens. Either kill the shell process and move on, keep it running and move on, or break and stop proceeding.
        • if done: true is set, keep the shell and the associated processes running and move onto the next step (Useful when you use the shell to launch some process that needs to keep running, such as web servers)
        • if kill: true is set, kill the shell session and all processes tied to the shell session before moving onto the next step.
        • if break: true is set, stop the shell and display a blue screen (error display screen) with the matched event pattern highlighted. For example if you want to break and stop the script from proceeding when the shell encounters "Exception", you may specify { event: "/exception/i", break: true }
        • if break: false is set, explicitly ignore the specified event pattern. For example, by default /Error:/ is captured, but if you want the script to ignore when the terminal encounters an Error: not critical pattern, you can specify { event: "/error: not critical/i", break: false }.
  • if NOT specified (default): The shell ends only when it reaches the next terminal prompt (when all the commands have finished running, which will trigger the prompt to display at the end again).
• <sudo>: (optional) run in admin mode when set to true.
  • on mac and linux, it runs the command with sudo <message>
  • on windows, it runs the command in administrator mode
• <cache>: (optional) cache path
  • the following subfolders will be generated under the cache folder, which will be programmatically populated when the apps run:
    • HF_HOME: huggingface cache. used to store model files downloaded from huggingface.
    • TORCH_HOME: pytorch hub cache. used to store model files downloaded from torch hub
    • GRADIO_TEMP_DIR: gradio cache. used to store files processed by gradio

• input:
  • id: The internal shell ID
  • stdout: The raw shell content
  • event: If the shell.run call had an on shell parser attached, the return value will have an event attribute, which is the regular expression match object from the first matched pattern in the <shell_event_handler>.

Example:

When running:

{
  "daemon": true,
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "python app.py",
      "venv": "env",
      "on": [{
        "event": "/http:\/\/[0-9.:]+/",
        "done": true
      }]
    }
  }, {
    "method": "local.set",
    "params": {
      "url": "{{input.event[0]}}"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "Running on {{local.url}}"
    }
  }]
}

The first step will return input as the following object:

{
  "id": "8e04df87-9b97-4e80-8e77-9224fcb0204f",
  "stdout": "\r\nThe default interactive shell is now zsh.\r\nTo update your account to use zsh, please run `chsh -s /bin/zsh`.\r\nFor more details, please visit https://support.apple.com/kb/HT208050.\r\n<<PINOKIO SHELL>> eval \"$(conda shell.bash hook)\" && conda deactivate && conda deactivate && conda deactivate && conda activate base && source /Users/x/pinokiomaster/api/comfyui.git/app/env/bin/activate /Users/x/pinokiomaster/api/comfyui.git/app/env && python main.py --force-fp16\r\n** ComfyUI startup time: 2024-04-06 22:53:40.865398\r\n** Platform: Darwin\r\n** Python version: 3.10.12 (main, Jul  5 2023, 15:02:25) [Clang 14.0.6 ]\r\n** Python executable: /Users/x/pinokiomaster/api/comfyui.git/app/env/bin/python\r\n** Log path: /Users/x/pinokiomaster/api/comfyui.git/app/comfyui.log\r\n\r\nPrestartup times for custom nodes:\r\n   0.0 seconds: /Users/x/pinokiomaster/api/comfyui.git/app/custom_nodes/ComfyUI-Manager\r\n\r\nTotal VRAM 65536 MB, total RAM 65536 MB\r\nForcing FP16.\r\nSet vram state to: SHARED\r\nDevice: mps\r\nVAE dtype: torch.float32\r\nUsing sub quadratic optimization for cross attention, if you have memory or speed issues try using: --use-split-cross-attention\r\n### Loading: ComfyUI-Manager (V2.7.2)\r\n### ComfyUI Revision: 1969 [02409c30] | Released on '2024-02-12'\r\n\r\nImport times for custom nodes:\r\n   0.1 seconds: /Users/x/pinokiomaster/api/comfyui.git/app/custom_nodes/ComfyUI-Manager\r\n\r\nStarting server\r\n\r\nTo see the GUI go to: http://127.0.0.1:8188",
  "event": [
    "http://127.0.0.1:8188"
  ]
}

• As a result, the local.url will be set to {{input.event[0]}} which evaluates to http://127.0.0.1:8188.
• And finally the last log step will print:

Running on http://127.0.0.1:8188

You can launch various CLI apps that require user interaction. For example, to launch with claude code:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "claude",
      "input": true
    }
  }]
}

To launch OpenAI Codex:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "codex",
      "input": true
    }
  }]
}

Note that input is false by default for all shell.run API requests. So you need to specify input: true if you want a shell.run call to launch an interactive shell.

You can either pass one message (string), or multiple messages (array):

If the message attribute is a single string, it simply enters that line into the shell.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": "env",
      "message": "pip install -r requirements.txt"
    }
  }]
}

If the message attribute is an array, it executes the commands in sequence.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": "env",
      "message": [
        "pip install -r requirements.txt",
        "pip install torch gradio"
      ]
    }
  }]
}

The path attribute is used to specify the path from which the shell starts.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "path": "app",
      "message": "python app.py"
    }
  }]
}

In this example, the shell starts from the app folder, basically running python for the app/app.py file.

The env attribute can be used to inject custom environment variables when starting the shell.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "env": {
        "PYTORCH_ENABLE_MPS_FALLBACK": "1"
      },
      "message": "python app.py"
    }
  }]
}

In this example, the PYTORCH_ENABLE_MPS_FALLBACK environment variable is set to "1" before running python app.py.

The venv attribute is used to declaratively activate a venv environment with just 1 line.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": ".env",
      "message": "python app.py"
    }
  }]
}

With just one line above, it either creates a venv at path .env (if it doesn't exist yet), and activates the environment for this specific shells session.

Basically, when the .env already exists, it's equivalent to:

source .env/bin/activate
python app.py

And when the .env doesn't exist, it's equivalent to:

python -m venv .env
source .env/bin/activate
python app.py

But you don't have to worry about any of this since with just one line "venv": ".env" this is handled automatically.

Note that the venv environment is ephemeral to the shell.run call, so when that shell session ends, the venv is no longer active.

For example:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "venv": "env1",
      "message": "python app.py"
    }
  }, {
    "method": "shell.run",
    "params": {
      "venv": "env2",
      "message": "python app.py"
    }
  }]
}

in the example above, the first shell.run runs in env1 environment, whereas the second shell.run runs in env2 environment. The two shell sessions are completely independent from each other.

The conda attribute

By default if you do not specify any conda attribute in shell.run, it will automatically activate the Pinokio-sandboxed base environment.

Even if you have a globally installed conda, it will NOT use your system-wide base environment, but use Pinokio's own base environment. This is to ensure everything works exactly the same for every user in every system.

For example the following will automatically activate the Pinokio base environment before starting the shell (which you can find in /PINOKIO_HOME/bin/miniconda):

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "python app.py"
    }
  }]
}

You can also create and/or activate a custom conda environment at a specific path:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "conda": "conda_env",
      "message": "python app.py"
    }
  }]
}

Above script will:

1. First check if there's a conda environment at path conda_env (relative to the current folder)
2. If there is one, activate the environment
3. If there is no conda environment there, create a conda environment at the location and activate it.
4. Finally start the shell session and run the command python app.py

You can also create/activate a conda environment by name. In this case you will need to use the object syntax instead of using string.

The difference is, instead of storing the conda environment at a specific path, the environment will be stored inside /PINOKIO_HOME/bin/miniconda.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "conda": {
        "name": "conda_env",
      },
      "message": "python app.py"
    }
  }]
}

Writing scripts that create custom conda environments by name is not recommended, because of potential name collision issues. If you really must use conda, create custom conda environments using path instead.

Normally you probably don't want to do this, but you can even avoid the default option of activating the base conda environment if you want.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "conda": {
        "skip": true
      },
      "message": "python app.py"
    }
  }]
}

You can create a custom conda environment with a custom python version using the conda.python attribute:

{
  "run": [{
    "method": "shell.run",
    "params": {
      "conda": {
        "path": "custom_python_conda_env",
        "python": "python=3.11"
      },
      "message": "python app.py"
    }
  }]
}

The on attribute lets you implement a realtime shell parser.

1. Monitor the shell content in realtime
2. When one of the specified events match, move on to the next step along with the matched pattern as input.event
3. Additionally, specify whether to kill the shell process (kill) or keep it running (done)

{
  "daemon": true,
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "python app.py",
      "venv": "env",
      "on": [{
        "event": "/http:\/\/[0-9.:]+/",
        "done": true
      }]
    }
  }, {
    "method": "local.set",
    "params": {
      "url": "{{input.event[0]}}"
    }
  }]
}

Explanation:

1. method: Run a command with shell.run that starts a web server (python app.py)
2. venv: The shell is automatically activated to the venv at path env (relative path).
3. on: The on handler takes an array of multiple possible events (In this case just one event).
   • event The shell keeps running until the regular expression /http:\/\/[0-9.:]+/,
   • done: Since done: true is set, the behavior is to move onto the next RPC call while keeping the shell process running. This is needed because we want the python app.py process to keep running (it's a web server).
     • The return value of this method is { id, stdout, event } where:
       • id: the id of the terminal
       • stdout: the full content of the terminal
       • event: the regular expression match object (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match).
4. In the next step local.set, the input variable passed in from the previous step contains { id, stdout, event } attributes.
   • The input.event attribute is the regular expression match array from the previous step (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match).
   • we use the input.event[0] to set the local.url local variable.

Example:

{
  "daemon": true,
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "python app.py",
      "venv": "env",
      "on": [{
        "event": "/http:\/\/[0-9.:]+/",
        "kill": true
      }]
    }
  }, {
    "method": "local.set",
    "params": {
      "url": "{{input.event[0]}}"
    }
  }]
}

Same as the done: true case, but in this case, the kill: true is set, therefore when the event match happens, the shell session as well as all its associated processes are shut down before moving onto the next step.

Example:

// break.js
module.exports = {
  run: [{
    method: "shell.run",
    params: {
      message: "{{platform === 'win32' ? 'dir' : 'ls'}}",
      on: [{
        event: "/break.*js/",
        break: true
      }]
    }
  }]
}

Above script:

1. runs "dir" (on windows) or "ls" (on linux or mac)
2. if it encounters the pattern /break.*js/, it breaks with the following blue screen with the matched event break.js highlighted:

Run shell commands in admin mode.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "sudo": true,
      "message": "reg add HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f",
    }
  }]
}

In this case we are trying to set the registry value, which needs to be run in admin mode, and we can simply pass the sudo: true option to achieve this.

• app.launch
• app.search
• app.info
• app.refresh

Launch a desktop application by id or name. If the app is missing and an install URL is provided, Pinokio opens an install modal, waits for detection, handles macOS first-launch prompts, and then launches.

{
  "method": "app.launch",
  "params": {
    "id": "<app_id>",
    "app": "<app_name>",
    "args": [ "<arg>", "..." ],
    "refresh": <force_reindex>,
    "install": "<install_url>",
    "installTimeout": <milliseconds>,
    "installPollInterval": <milliseconds>
  }
}

• id: optional app id (preferred when known).
• app / name: app name to search for when id is unknown.
• args: optional command-line arguments passed to the app.
• refresh: force a rescan of installed apps before launching.
• install: URL to open if the app is missing. When set, Pinokio shows an install modal, polls until the app is detected, prompts for macOS “Open in Finder” confirmation if needed, then launches.
• installTimeout: how long to wait for detection during install flow (default 5 minutes).
• installPollInterval: detection poll interval during install flow (default 5 seconds).

An object describing the launch result, for example:

{
  "success": true,
  "id": "com.apple.Safari",
  "name": "Safari",
  "kind": "macos-bundle",
  "platform": "darwin",
  "detail": "com.apple.Safari",
  "pid": 12345,
  "confidence": 0.92
}

If the app is not found and no install is provided, the RPC throws an error with code: "APP_NOT_FOUND".

{
  "method": "app.launch",
  "params": {
    "app": "Safari"
  }
}

{
  "method": "app.launch",
  "params": {
    "app": "Cursor",
    "args": ["--new-window"],
    "install": "https://cursor.sh/",
    "installTimeout": 600000,
    "installPollInterval": 5000
  }
}

{
  "method": "app.search",
  "params": {
    "query": "<text>",
    "limit": <max_results>,
    "refresh": <force_reindex>
  }
}

• query: search text (app name, bundle id, executable name, etc.).
• limit: max results (default 25).
• refresh: force a rescan before searching.

Array of app entries. Each entry typically includes id, name, aliases, platform, kind, and detail (e.g., bundle id or path).

{
  "method": "app.search",
  "params": {
    "query": "chrome",
    "limit": 5
  }
}

{
  "method": "app.info",
  "params": {
    "id": "<app_id>",
    "refresh": <force_reindex>
  }
}

• id: required app id.
• refresh: force a rescan before returning info.

App metadata object: id, name, aliases, platform, kind, detail, and adapter-specific fields such as path/execPath when available.

{
  "method": "app.info",
  "params": {
    "id": "com.microsoft.VSCode",
    "refresh": true
  }
}

{
  "method": "app.refresh",
  "params": {
    "force": <boolean>
  }
}

• force: when true, rebuilds the app index from disk.

Adapter-specific refresh result (usually a success flag or summary).

{
  "method": "app.refresh",
  "params": {
    "force": true
  }
}

You can accept user input through the input API.

It can be used to receive custom human input and returns a key-value pairs object.

{
  "method": "input",
  "params": {
    "title": <The title of the input modal>,
    "description": <The description of the input modal>,
    "type": <input dialog type ("modal" or "notify")>,
    "form": [{
      "type": <input field type, for example 'text', 'password', etc. (optional)>,
      "key": <Input field 1 key (required)>,
      "title": <Input field 1 title>,
      "description": <Input field 1 description>,
      "placeholder": <Input field 1 placehoder>,
      "default": <the default value for field 1>
    }, {
      "type": <input field type, for example 'text', 'password', etc. (optional)>,
      "key": <Input field 2 key (required)>,
      "title": <Input field 2 title>,
      "description": <Input field 2 description>,
      "placeholder": <Input field 2 placehoder>,
      "default": <the default value for field 1>
    }, {
      ...
    }]
  }
}

The input API lets you insert an interactive modal in the workflow.

• title: The input modal title
• description: The input modal description
• form: The form array. Can include as many keys as you want.
  • key: (required) The field key
  • title: (optional) The field title (displayed above the input field)
  • description: (optional) The field description (displayed above the input field along with the title)
  • default: (optional) The default value for the field. If specified, the input field will be pre-filled with this value.
  • required: (optional) If set to true, the dialog will display an alert when trying to submit without setting this value.
  • placeholder: (optional) The placeholder text for the field.
  • type: (optional) The input field type, for example 'text', 'password', etc.
  • items: (optional. only for type: "select") items is an array that includes one or more objects that have the following attributes:
    • text: The text to display
    • value: The actual value to return when selected.
  • accept: (optional. only for type: "file") You can set the accept attribute so the file upload field only accepts certain types of files. The accept value is a comma separated value of one or more mime types.

By default if you do not specify the type, a text field is rendered.

1. text (default)
2. email
3. password
4. textarea
5. file
6. select
7. checkbox

This is the default input type. If you do not specify a type, a text field will be created.

{
  "method": "input",
  "params": {
    "title": "Login",
    "description": "Enter your credentials",
    "form": [{
      "key": "username",
      "title": "Username",
      "description": "Enter the username",
      "placeholder": "(ex: cocktailpeanut, etc.)",
      "default": ""
    }]
  }
}

This is the default input type. If you do not specify a type, a text field will be created.

{
  "method": "input",
  "params": {
    "title": "Login",
    "description": "Enter your credentials",
    "form": [{
      "key": "username",
      "title": "Username",
      "description": "Enter the username",
      "placeholder": "(ex: cocktailpeanut, etc.)",
      "default": ""
    }, {
      "type": "email",
      "key": "email",
      "title": "e-mail",
      "description": "Enter the email",
    }]
  }
}

This is the default input type. If you do not specify a type, a text field will be created.

{
  "method": "input",
  "params": {
    "title": "Login",
    "description": "Enter your credentials",
    "form": [{
      "key": "username",
      "title": "Username",
      "description": "Enter the username",
      "placeholder": "(ex: cocktailpeanut, etc.)",
      "default": ""
    }, {
      "type": "email",
      "key": "email",
      "title": "e-mail",
      "description": "Enter the email",
    }, {
      "type": "password",
      "key": "pw",
      "title": "Password",
      "description": "Enter the password",
    }]
  }
}

{
  "method": "input",
  "params": {
    "title": "Prompt",
    "description": "Enter a prompt",
    "form": [{
      "type": "textarea",
      "key": "prompt",
      "title": "Prompt",
    }]
  }
}

{
  "method": "input",
  "params": {
    "title": "Profile",
    "description": "Upload an avatar",
    "form": [{
      "type": "file",
      "key": "avatar",
      "title": "Avatar",
    }]
  }
}

To manipulate the file object returned from the input API, it is recommended to use the custom inline JavaScript API to handle the uploaded file. Since it's just JavaScript, you can do anything with the uploaded Buffer.

Here's an example:

const path = require('path')
const fs = require('fs')
module.exports = {
  run: [{
    method: "input",
    params: {
      title: "Upload File",
      form: [{
        title: "Image",
        description: "upload a png image",
        key: "image",
        type: "file",
        accept: "image/png"
      }]
    }
  }, {
    method: async (req, ondata, kernel) => {
      console.log("req.input", req.input)
      await fs.promises.writeFile(
        path.resolve(req.cwd, "image.png"),
        req.input.image
      )
    }
  }]
}

In above example:

1. First use the input API to upload a file under the name image.
2. This is made available in step 2, which is a custom JavaScript inline API. The uploaded file is available as req.input.image as a Buffer object.
3. The file is saved as image.png.

{
  "run": [{
    "method": "input",
    "params": {
      "title": "Select",
      "form": [{
        "type": "select",
        "key": "selection",
        "items": [{
          "text": "United States",
          "value": "US"
        }, {
          "text": "France",
          "value": "FR"
        }, {
          "text": "Japan",
          "value": "JP"
        }, {
          "text": "Korea",
          "value": "KO"
        }, {
          "text": "Canada",
          "value": "CA"
        }]
      }]
    }
  }, {
    "method": "log",
    "params": {
      "raw": "Selected: {{input.selection}}"
    }
  }]
}

{
  "run": [{
    "method": "input",
    "params": {
      "title": "Checkbox",
      "form": [{
        "type": "checkbox",
        "title": "tall",
        "description": "check if you're tall",
        "key": "tall"
      }, {
        "type": "checkbox",
        "title": "fat",
        "description": "check if you're fat",
        "key": "fat"
      }]
    }
  }, {
    "method": "log",
    "params": {
      "json2": "{{input}}"
    }
  }]
}

The return value will set the value of the keys as either true (checked) or false (not checked).

For example, if you check the tall checkbox and leave the fat checkbox unchecked, the step 2 will print the following:

prints

{
  "tall": true,
  "fat": false
}

Once the user clicks the "done" button to close the dialog, The input API will return the key-value pairs constructed from the form.

Here's an example where you can accept a username and a password:

{
  "run": [{
    "method": "input",
    "params": {
      "title": "Login",
      "form": [{
        "key": "username",
        "title": "username"
      }, {
        "key": "password",
        "title": "password",
      }]
    }
  }, {
    "method": "net",
    "params": {
      "url": "https://mywebsite.com",
      "method": "post",
      "data": {
        "username": "{{input.username}}",
        "password": "{{input.password}}"
      }
    }
  }]
}

First, we use the input API to display a modal with a form to construct an object with the keys: username and password.

When the user enters the username and the password and presses "done", the input API will return the following value:

{
  "input": {
    "username": "cocktailpeanut",
    "password": "7gproteinperserving"
  }
}

This then can be used in the second API call (net) to make a network API request.

While you can upload files using the file type fields via the input API, this only lets you upload files.

It does NOT give you an option to:

1. Just get the path of a selected file WITHOUT uploading the file
2. Just get the path of a selected folder WITHOUT uploading anything, and use this path in subsequent steps.

For example, you may want to let the user select a specific path and run some actions on the path, and this may have nothing to do with uploading files.

{
  method: "filepicker.open",
  params: {
    "title": <dialog_title>,
    "type": <type>,              := folder | file (default)
    "path": <path>,               := <cwd to open from>
    "filetypes": <filetypes>,         := <file types to accept> (example:   [["Images", "*.png *.jpg *.jpeg"]] )
    "multiple": <multiple>,          := True | False (allow multiple)
  }
}

• <dialog_title>: The picker dialog title
• <type>: folder or file. If not specified, the default value is file.
• <path>: (optional) The folder path to open the dialog from. If not specified, selected by the system.
• <filetypes>: An array of file types (powered by Tkinter Filedialog) (Example: "filetypes": [["Images", "*.png *.jpg *.jpeg"]])
• <multiple>: true or false. if set to true, allows multiple file selection

The filetypes field is an array of arrays. Here are some examples:

Allow Images Only

{
  "filetypes": [["Images", "*.png *.jpg *.jpeg"]]
}

Allow Images and text files

{
  "filetypes": [
    ["Images", "*.png *.jpg *.jpeg"],
    ["Text files", "*.txt"],
  ]
}

returns an array of the selected file paths

{
  paths: [
    ...,
    ....
  ]
}

{
  "run": [{
    "method": "filepicker.open",
    "params": {
      "path": "images"
    }
  }, {
    "method": "fs.open",
    "params": {
      "action": "view",
      "path": "{{input.paths[0]}}"
    }
  }]
}

1. Open a file picker (at the images path from the current folder)
2. When the user selects a file, the selected path is returned as an item in the input.paths array. In this case since it's just a single selection, the paths array should have only one item.
3. The step 2 then can open the file explorer at input.paths[0].

• fs.write
• fs.read
• fs.rm
• fs.copy
• fs.download
• fs.link
• fs.open
• fs.cat

The fs api provides a simple way to write json, text, or buffer to the file system.

{
  "method": "fs.write",
  "params": {
    "path": <path>,
    <type>: <data>
  }
}

• <path>: the file path to write to (see distributed file URI)
• <type>: "json", "json2", "text", or "buffer". The <data> is treated as the type specified by the <type> value when writing to the file.
• <data>: the data to write to the file.

none

Here's a simple example to write JSON to items.json

{
  "method": "fs.write",
  "params": {
    "path": "items.json",
    "json": {
      "names": [ "alice", "bob", "carol" ]
    }
  }
}

This will result in a file named items.json looking like this:

{"names":["alice","bob","carol"]}

The json type writes the entire JSON in a single line. If we want to write a multiline JSON, use json2 type:

{
  "method": "fs.write",
  "params": {
    "path": "items.json",
    "json2": {
      "names": [ "alice", "bob", "carol" ]
    }
  }
}

This will result in items.json looking like this:

{
  "names": [
    "alice",
    "bob",
    "carol"
  ]
}

{
  "method": "fs.write",
  "params": {
    "path": "items.csv",
    "text": "alice,bob,carol"
  }
}

This will result in items.csv that looks like this:

alice,bob,carol

Converting a base64 string to Buffer and writing to img.png:

{
  "method": "fs.write",
  "params": {
    "path": "img.png",
    "buffer": "{{Buffer.from(input.images[0], 'base64')}}"
  }
}

The fs api provides a simple way to read from files.

{
  "method": "fs.read",
  "params": {
    "path": <path>,
    "encoding": <encoding>
  }
}

• <path>: the file path to read from (see distributed file URI)
• <encoding>: the data encoding to read as. can be one of the following ("buffer" if not specified)
  • "ascii"
  • "base64"
  • "base64url"
  • "hex"
  • "utf8"
  • "utf-8"
  • "binary"

Internally, the API calls the fs.readFile node.js method:

fs.readFile(params.path, params.encoding)

• input: the file content

example (read img.png and print its base64 encoded string):

{
  "run": [{
    "method": "fs.read",
    "params": {
      "path": "img.png",
      "encoding": "base64"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "data:image/png;base64,{{input}}"
    }
  }]
}

The fs.rm API deletes a file or a folder at the specified path

{
  "method": "fs.rm",
  "params": {
    "path": <path>
  }
}

• <path>: the file path to write to (see distributed file URI)

none

example: Delete the folder app in the current directory.

{
  "run": [{
    "method": "fs.rm",
    "params": {
      "path": "app"
    }
  }]
}

The fs.copy API copies a file or a folder at src to dest

{
  "method": "fs.copy",
  "params": {
    "src": <source_path>,
    "dest": <destination_path>
  }
}

• <source_path>: the source file to copy from (see distributed file URI)
• <destination_path>: the destination file to copy to (see distributed file URI)

none

example: Copying hello.txt to world.txt

{
  "run": [{
    "method": "fs.copy",
    "params": {
      "src": "hello.txt",
      "dest": "world.txt"
    }
  }]
}

example: Copying the folder app to a new folder api recursively

{
  "run": [{
    "method": "fs.copy",
    "params": {
      "src": "app",
      "dest": "api"
    }
  }]
}

The fs.download downloads a file to a specified path or directory. If the path does not exist, it is created first if possible.

{
  "method": "fs.download",
  "params": {
    "uri": <uri>,
    <type>: <path>
  }
}

• <uri>: download file url(s). can be:
  • a url
  • an array of urls
• <type>: can be either "path" or "dir"
• <path>: the destination path.
  • if the <type> is "path": the file path to download as (see distributed file URI)
  • if the <type> is "dir": the directory path to download the file into. The remote filename will be preserved. (see distributed file URI)

none

example: Download https://via.placeholder.com/600/92c952 to a file named placeholder.png

{
  "run": [{
    "method": "fs.download",
    "params": {
      "url": "https://via.placeholder.com/600/92c952",
      "path": "placeholder.png"
    }
  }]
}

example: Download the file at https://huggingface.co/stabilityai/sdxl-turbo/resolve/main/sd_xl_turbo_1.0.safetensors?download=true under the models folder

{
  "run": [{
    "method": "fs.download",
    "params": {
      "url": "https://huggingface.co/stabilityai/sdxl-turbo/resolve/main/sd_xl_turbo_1.0.safetensors?download=true",
      "dir": "models"
    }
  }]
}

example: Download multiple files into a dir

{
  "run": [{
    "method": "fs.download",
    "params": {
      "uri": [
        "https://huggingface.co/justimyhxu/GRM/blob/main/grm_u.pth",
        "https://huggingface.co/cocktailpeanut/sv3/blob/main/sv3d_p.safetensors"
      ],
      "dir": "app/checkpoints"
    }
  }]
}

The fs.link API provides an easy way to store data outside of the repository through a mechanism called Pinokio Virtual Drive.

Virtual drives let you store data outside of applications and reference them from the apps without changing anything. Useful for many things, such as:

1. Storing files that persist across multiple installs (Similar to Docker Volumes)
2. Sharing files across multiple apps (such as AI model .safetensor files)
3. Storing all the library files (such as pytorch) in a deduplicated manner

Learn more about Virtual Drives here

Here are the operations supported by the fs.link API:

1. folder linking: link any folder paths within the current repository to corresponding virtual drive paths
2. peer linking: optionally, you can create a shared drive among multiple applications by declaring them as peer drives. It works the same sa folder linking, except it first checks if there's already an existing peer drive before creating one. If there is one already, the discovered peer drive is used instead of creating one.
3. venv linking: a special link method, which automatically links every installed python package inside a venv environment to each corresponding drive path.
   • useful for saving disk space by automatically deduplicating redundant packages (such as pytorch, etc.) across multiple apps.

You can link folders to virtual drive counterparts with:

{
  "method": "fs.link",
  "params": {
    "drive": {
      <drive_folder_path>: <actual_folder_path>,
      <drive_folder_path>: <actual_folder_path>,
      ...
    }
  }
}

Every fs.link call creates a virtual drive designated for the current repository, and then links the specified virtual paths to the actual path counterparts.

• <drive_folder_path>: a relative path within the virtual drive path to create
• <actual_folder_path>: the actual relative folder path within this repository.
  • Must be a folder path (no file paths)
  • May be a string or an array
  • When an array is used, all paths in the <actual_folder_path> array will turn into symbolic links that point to the corresponding <drive_folder_path> virtual drive path.

Here's an example:

// /PINOKIO_HOME/api/APP1/install.json

{
  "method": "fs.link",
  "params": {
    "drive": {
      "checkpoints": "app/models/checkpoints",
      "clip": "app/models/clip",
      "vae": "app/models/vae"
    }
  }
}

1. The fs.link call first creates a virtual drive for the current repository (/PINOKIO_HOME/api/APP1)
2. It then merges all the files inside app/models/checkpoints, app/models/clip, app/models/vae into the corresponding virtual drive folders (checkpoints, clip, vae)
3. Finally, it creates symbolic links to link the actual paths to the virtual drive paths:
   • from app/models/checkpoints, app/models/clip, and app/models/vae to
   • to the created virtual drive paths for this repository at checkpoints, clip, and vae each.

Let's walk through each step one by one.

NOTE

The following sections simply explain how the fs.link API works internally, and not something you need to do yourself. All these steps are taken care of by the fs.link API automatically.

Just read to understand what exactly happens when you run the fs.link API.

The fs.link first creates a virtual drive for the current repository. A unique folder for the current repository is created under /PINOKIO_HOME/drive/drives/peers.

Here's an example:

/PINOKIO_HOME
  /drive
    /drives
      /peers  
        /d1711553147861       <= virtual drive

The next step is to create the virtual drive folders from the keys under the params.drive, in this case:

• checkpoints
• clip
• vae

We end up with a virtua drive at the following paths:

/PINOKIO_HOME
  /drive
    /drives
      /peers  
        /d1711553147861       <= virtual drive
          /checkpoints
          /clip               
          /vae

Next, if there were any existing files inside the application folders, we need to merge them into the virtual drive folders, since we are about to turn these folders into symbolic links.

The merging is necessary, because otherwise all those files will be lost during the process, since the original folders will turn into symbolic links in the next step.

Pinokio uses a merging algorithm to merge the files at path:

• /PINOKIO_HOME/api/APP1/app/models/checkpoints
• /PINOKIO_HOME/api/APP1/app/models/clip
• /PINOKIO_HOME/api/APP1/app/models/vae

into the virtual drive folders:

• /PINOKIO_HOME/drive/drives/peers//d1711553147861/checkpoints
• /PINOKIO_HOME/drive/drives/peers//d1711553147861/clip
• /PINOKIO_HOME/drive/drives/peers//d1711553147861/vae

At the end of this step, the original application folders will be empty, and all the files will now be in the virtual drive folders.

Finally we finish the process by linking the application folders to the corresponding drive folders:

/PINOKIO_HOME/api/APP1/app/models/checkpoints => /PINOKIO_HOME/drive/drives/peers//d1711553147861/checkpoints
/PINOKIO_HOME/api/APP1/app/models/clip        => /PINOKIO_HOME/drive/drives/peers//d1711553147861/clip
/PINOKIO_HOME/api/APP1/app/models/vae         => /PINOKIO_HOME/drive/drives/peers//d1711553147861/vae

The app will work exactly the same as before, because when the app tries to access the application folders, they will be redirected by the symbolic links to the virtual drive folders.

Now if we download a file named sd_xl_turbo_1.0_fp16.safetensors into /PINOKIO_HOME/api/APP1/app/models/checkpoints, the actual file will be stored in the linked virtual drive folder like this:

/PINOKIO_HOME
  /api
    /APP1
      /app
        /models
          /checkpoints => symbolic liink to /drive/drives/peers/d1711553147861/checkpoints
    /APP2
    /APP3
    ...
  /drive
    /drives
      /peers
        /d1711553147861
          /checkpoints
            sd_xl_turbo_1.0_fp16.safetensors
        ...
  /logs
  /bin
  /cache

However you will still be able to access the sd_xl_turbo_1.0_fp16.safetensors file as if it's inside /PINOKIO_HOME/api/APP1/app/models/checkpoints thanks to the symbolic link system.

Now, what if we want to share a single virtual drive among multiple apps? For example, let's say we have 3 different Stable Diffusion apps named Stable-Diffusion-WebUI, ComfyUI, and Fooocus, and they all use the same AI model files.

How can we create a virtual drive so it can be shared by all 3 apps?

We can achieve this by declaring peers when creating a virtual drive with fs.link:

{
  "method": "fs.link",
  "params": {
    "drive": {
      <drive_folder_path>: <actual_folder_path>,
      <drive_folder_path>: <actual_folder_path>,
      ...
    },
    "peers": <peers>
  }
}

• <peers>: an array of git repository URIs

The only difference from plain folder linking is that there's a peer array.

When a peers array is declared, the fs.link API runs the following logic first BEFORE attempting to create its own virtual drive folders:

1. Loop through the peers array, and for each peer check if there is any virtual drive already created.
2. If a virtual drive is found for a peer, use that drive instead of creating a new drive.
3. If no virtual drive is found for any of the specified git repositories in the peers array, create a virtual drive using the folder linking method.

Let's take a look at a specific example, where we will write scripts for fooocus, stable-diffusion-webui, and comfyui so they all declare one another as peers:

Install script in https://github.com/cocktailpeanutlabs/fooocus.git

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "git clone https://github.com/lllyasviel/Fooocus app"
    }
  }, {
    "method": "fs.link",
    "params": {
      "drive": {
        "checkpoints": "app/models/checkpoints",
        "clip": "app/models/clip",
        "clip_vision": "app/models/clip_vision",
        "configs": "app/models/configs",
        "controlnet": "app/models/controlnet",
        "diffusers": "app/models/diffusers",
        "embeddings": "app/models/embeddings",
        "gligen": "app/models/gligen",
        "hypernetworks": "app/models/hypernetworks",
        "inpaint": "app/models/inpaint",
        "loras": "app/models/loras",
        "prompt_expansion": "app/models/prompt_expansion",
        "style_models": "app/models/style_models",
        "unet": "app/models/unet",
        "upscale_models": "app/models/upscale_models",
        "vae": "app/models/vae",
        "vae_approx": "app/models/vae_approx"
      },
      "peers": [
        "https://github.com/cocktailpeanutlabs/automatic1111.git",
        "https://github.com/cocktailpeanutlabs/comfyui.git"
      ]
    }
  }]
}

Install script in https://github.com/cocktailpeanutlabs/automatic1111.git

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui app"
    }
  }, {
    "method": "fs.link",
    "params": {
      "drive": {
        "checkpoints": "app/models/Stable-diffusion",
        "vae": "app/models/VAE",
        "loras": [
          "app/models/Lora",
          "app/models/LyCORIS"
        ],
        "upscale_models": [
          "app/models/ESRGAN",
          "app/models/RealESRGAN",
          "app/models/SwinIR"
        ],
        "embeddings": "app/embeddings",
        "hypernetworks": "app/models/hypernetworks",
        "controlnet": "app/models/ControlNet"
      },
      "peers": [
        "https://github.com/cocktailpeanutlabs/comfyui.git",
        "https://github.com/cocktailpeanutlabs/fooocus.git"
      ]
    }
  }]
}

Install script in https://github.com/cocktailpeanutlabs/comfyui.git

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "git clone https://github.com/comfyanonymous/ComfyUI.git app"
    }
  }, {
    "method": "fs.link",
    "params": {
      "drive": {
        "checkpoints": "app/models/checkpoints",
        "clip": "app/models/clip",
        "clip_vision": "app/models/clip_vision",
        "configs": "app/models/configs",
        "controlnet": "app/models/controlnet",
        "embeddings": "app/models/embeddings",
        "loras": "app/models/loras",
        "upscale_models": "app/models/upscale_models",
        "vae": "app/models/vae"
      },
      "peers": [
        "https://github.com/cocktailpeanutlabs/automatic1111.git",
        "https://github.com/cocktailpeanutlabs/fooocus.git"
      ]
    }
  }]
}

Each of the three scripts declares the rest 2 as the peers:

So how does this work in practice?

1. When any of these three scripts are run for the first time, there will be no existing "peer drive", therefore a new virtual drive will be created for the respository.
2. Then later if you run one of the other scripts, it will first run the peers check to discover any existing peer.
3. Since a peer virtual drive was already created in step 1, the virtual drive created in step 1 will used when running the rest of the fs.link folder linking, instead of creating a new drive.

One of the most frequently encountered use cases is dealing with redundant packages installed into venv environments across multiple apps.

Let's imagine the following scenario where we have 3 different apps APP1, APP2, and APP3, each with its own independent venv environment:

/PINOKIO_HOME
  /api
    /APP1
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch
              /accelerate
              /xformers
    /APP2
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch
              /accelerate
              /xformers
    /APP3
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch
              /accelerate
              /xformers

1. ALL of these apps have the same redundant packages installed (torch, accelerate, xformers, etc.)
2. However this is how venv is supposed to work. The whole point of venv is to isolate environments, so each environment is not supposed to know about other environments on the same machine.
3. It would still be nice to take advantage of the isolated environments we get from venv, while removing redundancy, so we can save some disk space.

And this is where the venv linking comes in.

For this special use case, there's an automated way to create virtual drives, with just one line.

{
  "method": "fs.link",
  "params": {
    "venv": <venv_path>
  }
}

• <venv_path>: The venv folder path to create virtual drive links for.

This will:

1. look into all the pip packages installed into the venv at <venv_path>
2. automatically create virtual drives for each unique version of the installed packages
3. automatically merge the package files inside the <venv_path> into the virtual drive paths
4. automatically create symbolic links from all the folders inside the original <venv_path> site-packages folder pointing to the automatically created virtual drive folders.

Unlike the folder linking method which creates a unique virtual drive for every repository, there is a single centralized pip drive organized as follows:

/PINOKIO_HOME
  /drive
    /drives
      /pip
        /accelerate
          /0.20.3
          /0.21.0
          /0.28.0
        /torch
          /2.1.0
          /2.2.2
        ...

Basically, every unique version of a unique library installed has its unique folder path.

When you call fs.link on a venv environment path, here's what happens:

1. Pinokio scans through the specified venv folder to find all installed packages
2. Then for every package in the venv, it looks up /PINOKIO_HOME/drive/drives/pip/<package_name>/<version> to check if it already exists in the virtual drive
3. If it already exists, just use that one
4. If it does NOT exist, create the library's version folder (for example /PINOKIO_HOME/drive/drives/pip/torch/2.3.0), move all files into the drive, and create a symbolic link

This way, each library path in the venv will be nothing more than a symbolic link to the created drive path.

Here's what the end result may look like for the original 3 apps example from above:

/PINOKIO_HOME
  /drive
    /drives
      /pip
        /accelerate
          /0.20.3
          /0.21.0
          /0.28.0
        /torch
          /2.1.0
          /2.2.2
        /xformers
          /0.0.25
          /0.0.24
        ...
  /api
    /APP1
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch          => link to /PINOKIO_HOME/drive/drives/pip/torch/2.2.2
              /accelerate     => link to /PINOKIO_HOME/drive/drives/pip/accelerate/0.28.0
              /xformers       => link to /PINOKIO_HOME/drive/drives/pip/xformers/0.0.25
    /APP2
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch          => link to /PINOKIO_HOME/drive/drives/pip/torch/2.2.2
              /accelerate     => link to /PINOKIO_HOME/drive/drives/pip/accelerate/0.28.0
              /xformers       => link to /PINOKIO_HOME/drive/drives/pip/xformers/0.0.25
    /APP3
      requirements.txt
      app.py
      /venv
        /lib
          /python3.10
            /site-packages
              /torch          => link to /PINOKIO_HOME/drive/drives/pip/torch/2.2.2
              /accelerate     => link to /PINOKIO_HOME/drive/drives/pip/accelerate/0.28.0
              /xformers       => link to /PINOKIO_HOME/drive/drives/pip/xformers/0.0.25

1. Note that the /torch, /accelerate, and xformers folders are all pointing to the shared virtual drive folders. This is already saving tons of disk space by removing the redundancy.
2. At the same time, each app works EXACTLY the same as before because these are symbolic links, and they all behave as if these pip packages are actually stored in each app's venv site-packages folders (but in reality they are just symbolic links pointing to the shared pip virtual drive)

The fs.open api opens a file explorer for a given path

{
  "method": "fs.open",
  "params": {
    "path": "<path>",
    "action": <action>
  }
}

• <path>: the file path to open in a file explorer
• <action>: (optional) may be either view or open. If not specified, it opens in the view mode.
  • view: open the file path in file explorer.
  • open: open the file itself at the file path, using the default app.
  • any other command: use the action as a command to open the path. (ex: cursor)

none

Open a folder in file explorer

{
  "method": "fs.open",
  "params": {
    "path": "outputs"
  }
}

which is equivalent to:

{
  "method": "fs.open",
  "params": {
    "path": "outputs",
    "action": "view"
  }
}

Open a file (with whichever app is the default handler)

{
  "method": "fs.open",
  "params": {
    "path": "outputs",
    "action": "open"
  }
}

Open a file with Cursor

{
  "method": "fs.open",
  "params": {
    "path": "app.js",
    "action": "cursor"
  }
}

Above script will call cursor app.js.

The fs.cat api prints the contents of a file

{
  "method": "fs.cat",
	"params": {
		"path": "<path>"
	}
}

• <path>: the file path to print in terminal

none

By default, Pinokio steps through all the requests in the run array and halts at the end.

However you can implement looping, which will let you build all kinds of interesting perpetual workflows.

{
  "method": "jump",
  "params": {
    <key>: <value>,
    "params": <params>
  }
}

• <key>: can be either "index" or "id"
  • index: jump to the index position in the run array
  • id: jump to the position tagged as id
• <value>
  • if <key> is "index", jump to the specified <value> position within the run array (For example if "index": 3, jump to run[3].
  • if <key> is "id", jump to a step tagged with an id of <value>.
• <params>: (optional) Sometimes you may want to pass arguments to the next step. The <params> value will be available as "input" inside the next step when using a template expression.

none

{
  "run": [{
    "method": "jump",
    "params": {
      "index": 2
    }
  }, {
    "method": "log",
    "params": {
      "raw": "hello"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "world"
    }
  }]
}

This will print:

world

{
  "run": [{
    "method": "jump",
    "params": {
      "id": "w"
    }
  }, {
    "method": "log",
    "params": {
      "raw": "hello"
    }
  }, {
    "id": "w",
    "method": "log",
    "params": {
      "raw": "world"
    }
  }]
}

This will print:

world