Pinokio Documentation

Pinokio is a 1-click launcher for open-source projects. It acts as a user-friendly terminal interface that can programmatically interact with scripts to run commands, download files, and execute processes.

Users can interact with scripts in two ways:

1. Write and run local scripts: Create and execute your own scripts locally, similar to writing shell scripts.
2. Install from the 'Discover' page: Use vetted, secure scripts that are manually listed, tracked via Git, and managed under the official Pinokio GitHub organization.

Pinokio is designed to run scripts in an isolated environment to minimize security risks.

• Storage Isolation: By default, all scripts run under an isolated location at ~/pinokio/api.
• Binary Isolation: All binaries installed via built-in package managers (Conda, Homebrew, Pip, and NPM) are stored within ~/pinokio/bin.
• Environment Isolation: Everything performed within Pinokio is stored inside the ~/pinokio directory.
• Transparency: All scripts must be downloaded from public Git repositories and are written in human-readable JSON syntax, allowing users to inspect the source code before execution.

To have a script featured on the official 'Discover' page, it must undergo a strict verification and transfer process:

1. Publisher Verification: Contact the Pinokio admin (@cocktailpeanut on X) to request personal verification.
2. GitHub Organization Invitation: Once verified, you will be invited to the Pinokio Factory GitHub organization as a contributor.
3. Repository Transfer: You must transfer your script repository to the Pinokio Factory GitHub organization. This makes the repository 'frozen' under the organization's control.
4. Feature Application: After the transfer is complete, request to feature the script by contacting the admin.
5. Review: The Pinokio admin will thoroughly review and test the script for security, ensuring it respects isolation boundaries (path checks, venv checks, and 3rd party package checks).

When writing Pinokio scripts, use the path and venv attributes to ensure commands and dependencies remain isolated within the application's directory.

• path: Declares the folder path from which to run a command. If not specified, the default execution path is the application's path.
• venv: Automatically activates a virtual environment and installs dependencies within the application's folder.

Example of a script method that installs Python dependencies using uv within a specific subfolder and virtual environment:

{
  "method": "shell.run",
  "params": {
    "message": "uv pip install -r requirements.txt",
    "path": "server",
    "venv": "venv"
  }
}