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.
- 1Add the manifest
Tell PicoRunner what your app needs and how to open it.
- 2Test in PicoRunner
Install it from scratch, open it, and try an update.
- 3Add 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.
It keeps your intended setup explicit and repeatable. Validation errors are shown before installation so you can correct the manifest.
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.
| Section | What it controls | Required |
|---|---|---|
runtime | Node or Python version, package manager, and workspace. | Yes |
setup | Locked dependency installation and explicit build steps. | No |
launch | Command, working directory, loopback host, port, and fixed environment. | Yes |
health | HTTP or TCP readiness check and timeout. | No |
persistence | Repository-relative files and folders that survive managed updates. | No |
inputs | Required configuration and secret names—never their values. | No |
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.
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
- Check the file
Run
taplo check picorunner.tomlto catch TOML syntax errors. - Test a clean installation
Import the repository or a local folder. Review the plan and let PicoRunner install from the lockfile.
- 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.
- Test an update
Update the app and check that its saved files and data are still there.
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.