PicoRunner

For developers and creatorsShare your app

Help more people use
what you build.

You’ve built something useful. Help it reach the people it was made for, including those who have never opened a terminal. PicoRunner gives your community a way to install and open your app, with a direct link back to your work.

What you get

A shorter path from sharing to trying.

A link people can act on.

Add a launch button to your README, or share its link with your community. People open your project in PicoRunner and choose whether to install it.

Your setup, made repeatable.

Describe your app’s requirements and launch steps in one file. PicoRunner uses them to prepare the app on each person’s computer.

Welcome a wider community.

Invite people who care about what your app does, whatever their technical experience. Give them a path to trying your work and sharing useful feedback.

Your work gets the credit.

Your code and community stay on GitHub. Catalog pages link to the original repository, credit the project, share its README, display its license, and invite people to star it.

Can I share an app I built with AI?

Yes. Experienced developers, first-time builders, and vibe coders are all welcome. Your project needs to be public and work with PicoRunner’s setup. Follow the steps below to prepare it, test it, and add a launch button.

Does my app need to be in the collection first?

No. You can share a launch link to a public GitHub project directly. People can review it in PicoRunner before installing. Being featured in the collection is a separate review.

Share directly with a launch link as soon as your app is ready. Catalog listings are curated separately; a listing is not required to use the launch button.

How to share

Prepare it once. Share it with your community.

Add a picorunner.toml file to your project. It tells PicoRunner how to install and open your app, check that its service is ready, and preserve the data paths you declare when people update.

  1. 1
    Add the manifest

    Tell PicoRunner what your app needs and how to open it.

  2. 2
    Test in PicoRunner

    Install it from scratch, open it, and try an update.

  3. 3
    Add the launch button

    Let people open your project in PicoRunner from its README.

Step 1

Create picorunner.toml

Start with this file at the repository root, then replace every example value with commands and paths already supported by your project.

PicoRunner follows this file.

It keeps your intended setup explicit and repeatable. Validation errors are shown before installation so you can correct the manifest.

picorunner.toml
schema = 1
name = "Example App"

[runtime]
kind = "node"
version = "22"
package_manager = "pnpm"
workspace = "."

[[setup.steps]]
kind = "dependencies"
locked = true

[launch]
command = ["pnpm", "run", "start"]
host = "127.0.0.1"
host_env = "HOST"
port = 3000
port_env = "PORT"

[health]
type = "http"
path = "/"
timeout_seconds = 90

[persistence]
paths = ["data", "uploads"]

[[inputs]]
name = "OPENAI_API_KEY"
kind = "secret"
required = false
description = "Required only for AI features."

Commands are argument arrays, never shell strings. Services must bind to 127.0.0.1.

Reference

Manifest fields

Include what your app needs to install, open, and keep its saved data.

SectionWhat it controlsRequired
runtimeNode or Python version, package manager, and workspace.Yes
setupLocked dependency installation and explicit build steps.No
launchCommand, working directory, loopback host, port, and fixed environment.Yes
healthHTTP or TCP readiness check and timeout.No
persistenceRepository-relative files and folders that survive managed updates.No
inputsRequired configuration and secret names—never their values.No
View the complete manifest reference

Step 2

Get help from your coding agent

Use a coding agent to help prepare your project for PicoRunner. Give it the PicoRunner developer skill. It covers the manifest, app scripts, validation, and README launch badge.

Agent prompt
Read the PicoRunner developer skill at https://picorunner.com/skills/picorunner-developer/SKILL.md and apply it to this repository. Update the app and its README as needed, validate what you can, and report what remains unverified.

Step 3

Try it from start to finish

  1. Check the file

    Run taplo check picorunner.toml to catch TOML syntax errors.

  2. Test a clean installation

    Import the repository or a local folder. Review the plan and let PicoRunner install from the lockfile.

  3. Check that the app works

    Confirm that the health check detects a ready service, then complete a primary task in the app to check the user experience.

  4. Test an update

    Update the app and check that its saved files and data are still there.

Ready to share? Add the launch button below and invite your community to try your app. The curated collection has a separate review.

Step 4

Add “Launch on PicoRunner”

Paste your public GitHub link below. Add the button to your README so people can review and install your app in PicoRunner.

PreviewLaunch on PicoRunner badge preview

Before publishing

Final review

  • The repository is public and the default branch contains picorunner.toml.
  • Every setup and launch command works from a clean checkout.
  • The service binds only to 127.0.0.1.
  • The health check proves the app and its required data service are ready.
  • All user-created data paths are declared under persistence.
  • No credentials or secret values are stored in the manifest.