Skip to content
On this page

File System


Everything is a file

Everything on Pinokio exists as a file.

Flat File

The Pinokio world is made up of files. Everything can be expressed with files.

More specifically, Pinokio lets you express everything using flat JSON files:

  1. Data: Data stored as JSON.
  2. Code: Code written in JSON (JSON-RPC).
  3. API: Automatically constructed API endpoints based on file path convention.
  4. UI: UI expressed in JSON (Autogenerated forms based on JSON Schema).
  5. Publishing: Because everything can be replicated deterministically through files, it becomes trivial to publish and share the AIs created using Pinokio.
    • Publish to Git to version control and allow others to easily clone or fork
    • Publish to IPFS or BitTorrent for decentralized AI publishing.
    • etc.

Unix Philosophy

The benefit of the "Everything is a file" approach is explained here:

Everything is a file is an idea that Unix, and its derivatives, handle input/output to and from resources such as documents, hard-drives, modems, keyboards, printers and even some inter-process and network communications as simple streams of bytes exposed through the filesystem name space. ... The advantage of this approach is that the same set of tools, utilities and APIs can be used on a wide range of resources and a number of file types. When a file is opened, a file descriptor is created, using the file path as an addressing system. The file descriptor is then a byte stream I/O interface on which file operations are performed

Pinokio follows the same philosophy and enjoys the same benefits.


  1. Shareable: Because all you need is JSON, it is not only easy to build complex workflows, but also easy to share the workflows, simply by publishing the files (to git, etc).
  2. Self-contained: Because everything (not just data, but also code) is stored and executed as a file, Pinokio does not have any dependency on some 3rd party system. You can build and publish a completely self contained archive of workflows and applications as a single file or a folder.
  3. Natively Modular: Everything existing as a file makes it easy to automatically separate a monolithic application (expressed in a single JSON file) out into multiple files (also expressed in JSON files)
  4. Dynamic data powered by templates: Since everything is stored as a flat file, we can implement dynamic data simply by incorporating template expressions in those files (), and they are all automatically decoded at runtime.
  5. Simplified Application Development: No complex configuration is needed for building applications. Simply write some JSON or JavaScript files and drop them under the project folder, and the app constructs itself.
  6. Cross platform: The flat file format makes it trivial to run the same logic on multiple different platforms.
  7. Easily extensible: The native JSON file format makes it easy to extend APIs and applications simply by modifying the JSON attributes.

JSON Protocol

It is important to note that Pinokio uses JSON not just for storing data and code, but also as the native protocol.

In addition to everything from data to code being stored as JSON, Pinokio can use JSON to integrate and and comunicate with ANY external processes and remote APIs. Some examples:

  1. Run any python script: To communicate with a python process, simply write a JSON file from the python process, or print JSON to stdout from the python script, and process the terminal stream using the Pinokio Shell Interface
  2. Call any external process: Going one step further, it's not just python you can run. If you can run something manually, Pinokio can automate it with a simple sh RPC, or utilize the Pinokio Shell Interface for more low level access and stream processing.
  3. Call external servers: JSON is the most popular data transmission format for most APIs. You can communicate with any external API using the net API and seamlessly incorporate it into applications.

Home directory

Pinokio stores everything inside the pinokio folder under the user home directory (~/pinokio).


  • windows: C:\Users\<username>\pinokio
  • linux: /home/<username>/pinokio
  • mac: /Users/<username>/pinokio

Folder structure

The top level directories look like the following:

    /api    # (~/pinokio/api) stores the user installed files
    /bin    # (~/pinokio/bin) stores binary files, such as cmake, git, python, etc.


The bin folder stores all the binaries commonly used by AI engines. Currently includes:

  • python (and pip)
  • node.js (and npm)
  • git (only on windows for now, since mac and linux mostly ships with git)
  • cmake used for building C projects
  • more coming soon (please request if you need something)


The api folder is where the user downloaded repositories are stored. An API folder can contain either of the following:

  1. downloaded from git: repositories you downloaded from git.
  2. locally created: you can manually create folders and work from there.