Building & Publishing an Agent on init-store
This is the contract for shipping an agent to init-store. It is written to be followed literally, whether you are a human developer or an AI coding agent generating the project: build to the rules here and your agent will validate, publish, and run on every user's machine without changes.
The model is deliberately git-like: keep a small folder in your own repo, then push it with one command.
init push ./my-agent
You write normal Python. You declare what the user must supply (their own API keys, databases, MCP servers) in one manifest file. Users download your agent and run it on their own computer; nothing they type or produce passes through init-store.
Everything is free. There is no price to set, no fee to build, and no cut. init-store is open source under the MIT license.
0. TL;DR (the whole thing on one screen)
- Make a folder with
inference.pydefiningdef run(inputs: dict) -> dict. - Add
agent.yaml(a name, and what the user must supply). - Sign in to the init app (or init-store.tech) with your email: you get a six-digit code, no password. Then connect GitHub on your account page. That is all it takes to build and share.
init loginonce on your machine, theninit push ./my-agent.- A new agent is private. Share it by email with the people who should have it. Listing it in the public store additionally needs more than 100 stars across your public repositories.
my-agent/
├── inference.py # REQUIRED — def run(inputs: dict) -> dict
├── agent.yaml # REQUIRED — the manifest
├── requirements.txt # optional — pip deps
└── helpers.py # optional — extra .py modules you import
Packaging limit: the bundle is the flat set of
*.pyfiles in the folder plusrequirements.txt— up to 16 modules, 64 KiB each, 256 KiB in total. Nested package directories and non-Python data files are not shipped. Keep modules flat next toinference.py.
1. The code contract — inference.py
Your entry file MUST define exactly one top-level function:
def run(inputs: dict) -> dict:
...
return {"answer": "..."} # MUST return a dict
inputs is a dict with three keys — identical when a user runs your agent from
the app, from the terminal, or while you test it with init run:
| key | what it is |
|---|---|
previous_output |
the caller's input (or the prior agent's output in a composed flow) |
step_config |
your agent's config (entry + files); usually ignored |
bindings |
the user's supplied values, keyed by the input names you declared |
Rules that are enforced (your run WILL fail if you break these):
runMUST return adict. Lists, strings, and other scalars are rejected, so outputs stay uniformly addressable when agents are chained.- The returned dict MUST be JSON-serialisable — no
set, nobytes, nodatetime(convert to ISO strings). - Raised exceptions are caught and reported as a failed run with the traceback — you don't need to wrap everything in try/except.
print()is tolerated, but only your returned dict is the output. Don't rely on stdout for return data.
Reading the user's keys (BYOK)
Every input you declare in agent.yaml is delivered to your code two ways —
use whichever you prefer:
import os
def run(inputs: dict) -> dict:
# 1) as an environment variable, named EXACTLY as you declared it
api_key = os.environ["OPENAI_API_KEY"]
# 2) or from the bindings dict
db_url = inputs["bindings"]["DATABASE_URL"]
...
The user brings their own keys (BYOM — bring your own model). You never hard-code or receive a key; you declare the slot and read it.
Scalars (
api_secret,db_connection, plain string) arrive both asos.environ[name]and ininputs["bindings"][name].file_urlandknowledge_handleare large/structured and arrive ininputs["bindings"]only (never the environment).
Runtime environment
- Your agent runs on the user's machine (Windows or Linux), in a Python
virtual environment the app creates for it, and installs your
requirements.txtinto that environment on first run. Users need Python 3.11, 3.12 or 3.13 installed. - Network egress is available — you can call OpenAI, Anthropic, your DB, etc. Remember the code runs with the user's permissions, so be a good guest: touch only what the task needs.
- Don't assume the init-store server is reachable at run time. Your agent should work with no connection to it.
Streaming progress (optional)
A long run shouldn't look like a hung one. Import plw_stream — it's injected by
the runner, so there's nothing to install or add to requirements.txt — and
narrate as you go. The text appears live in the app and in init run's terminal
output:
import plw_stream
def run(inputs):
plw_stream.progress("fetching", 10) # a labelled step, percentage optional
page = fetch(inputs["bindings"]["URL"])
plw_stream.log(f"got {len(page)} bytes") # a line of detail
answer = ""
for delta in llm_stream(page): # your model's own token stream
plw_stream.token(delta) # ...forwarded to the user, live
answer += delta
return {"answer": answer} # the result is still the return value
Three rules worth knowing:
- Streaming is narration, not the result. Whatever you
returnis still the agent's output; tokens you stream are shown while it works. - Plain
print()also surfaces, as a log line — so existing agents that print progress get this for free. Anything on stderr shows too. - It's optional and free to ignore. An agent that never imports
plw_streambehaves exactly as before.
Under the hood these are single-line JSON objects on stdout, so an agent in another language can emit them directly:
{"plw_event":"token","text":"Hel"}
{"plw_event":"log","text":"connected"}
{"plw_event":"progress","stage":"fetching","pct":10}
2. The manifest — agent.yaml
This declares what the user must connect (BYOK, databases, MCP servers) and how your listing reads.
name: pdf-summarizer # REQUIRED. Lowercase slug = your agent's stable
# id. Pushing the same name again updates the same
# agent (like pushing to the same git remote).
# Users install it as <your-github-login>/pdf-summarizer
description: Summarize a PDF using your own LLM key
version: 0.1.0 # optional, informational
entry: inference.py # optional. Defaults to inference.py, then main.py
runtime: python3.12 # optional. One of python3.11 | python3.12 | python3.13
category: productivity # optional. One lowercase word; defaults to "general"
# Optional: the agent's MEDIA contract — the media type it consumes and produces.
# This is what makes your agent pluggable when a user chains agents together:
# agents chain only when one's output type matches the next's input type.
# Omit it and your agent is treated as text -> text.
io:
input: text # text | audio | image
output: image # text | audio | image
output_format: png # optional, image/audio only (png | jpeg | wav | ...)
# Optional: declare your agent's LANGUAGE-MODEL dependency. `local_capable` tells
# users your agent can run on a model on THEIR machine (Ollama / vLLM), not only
# a cloud key — see "Running on a local model" below. Omit if you use no LLM.
llm:
required: true # the agent needs an LLM to run
local_capable: true # works against a local OpenAI-compatible server
# What the USER must supply. Each becomes an env var + a bindings entry + a field
# the app asks for. You declare the slot; the user fills the value.
inputs:
- name: OPENAI_API_KEY # the EXACT env-var name your code reads
type: api_secret # see "input types" below
description: Your OpenAI API key
where_to_get: https://platform.openai.com/api-keys # https only; shown to the user
required: true
- name: DATABASE_URL
type: db_connection
required: false
# Optional: MCP servers your agent calls. The user maps each slot to one of THEIR
# own servers in the app — you never embed an endpoint or token.
mcp:
- name: web-search
description: a web-search MCP server
There is no pricing setting: everything on init-store is free. A leftover
pricing: {model: free} block is accepted and ignored; any paid model is
rejected.
Input types (type:)
The type tells the app how to treat the value. Omit it for a plain string.
| type | meaning | kept in the user's vault | delivery |
|---|---|---|---|
api_secret |
an API key / token | yes | env + bindings |
db_connection |
a database connection string / DSN | yes | env + bindings |
llm_credential |
a model-provider credential | yes | bindings |
file_url |
a URL the agent reads from | no | bindings (content) |
knowledge_handle |
a reference to a knowledge source the user provides | no | bindings |
| (omitted) | a plain string | no | env + bindings |
Media type (io:) — what makes your agent composable
io.input / io.output declare the media type your agent consumes and
produces — one of text, audio, image (with an optional
*_format like png/jpeg/wav for image/audio). This is separate from
inputs: above: inputs are the user's key/value slots; io is the media
contract.
It exists for composition: a user can wire agents into a flow, and two
agents are pluggable only when the upstream agent's output type matches the
downstream agent's input type. Declare it accurately so your agent slots into
the flows it belongs in. Omitting io means text → text.
Running on a local model (llm:)
If your agent calls a language model, declare it with the llm: block.
local_capable: true advertises that your agent can run against a model on the
user's own machine — an Ollama or
vLLM server — so a user can run it fully offline with no
cloud key. The user registers their local endpoint in the app's vault, and the
app injects OPENAI_BASE_URL (and a key) into your run.
To be local-capable, use an OpenAI-compatible client and let it read the
environment — don't hard-code https://api.openai.com:
from openai import OpenAI
client = OpenAI() # reads OPENAI_BASE_URL + OPENAI_API_KEY from the env
When the user points the app at Ollama/vLLM, the same code runs against the
local model; with a cloud key it runs against the cloud. One caveat: the model
name you request must be one the user's server serves (Ollama: tag it; vLLM:
--served-model-name). Cloud-only agents just set required: true and omit
local_capable.
The name is the contract. For a secret to reach os.environ["GROQ_API_KEY"],
declare an input named exactly GROQ_API_KEY. The input name is
simultaneously the env-var name your code reads and the label the user stores in
their vault — they must match character-for-character.
MCP & BYOK, restated
- You declare the shape in
agent.yaml(which keys, which MCP slots). - The user supplies the actual values and endpoints on their machine.
- Their data and credentials stay on their side. init-store holds a catalog of agents and a list of accounts, and nothing else.
3. Standards checklist (self-verify before you push)
A compliant agent satisfies all of these. An AI generating an agent should check the project against this list before pushing.
Code
-
inference.py(or yourentry) definesdef run(inputs: dict) -> dict. -
runreturns a JSON-serialisabledicton every path. - Reads each user value via
os.environ[NAME]orinputs["bindings"][NAME], whereNAMEmatches a declared input — never a hard-coded secret. - All modules are flat
.pyfiles besideinference.py(no sub-packages). - Third-party imports are pinned in
requirements.txt. - No assumption that the init-store server is reachable at run time.
Manifest (agent.yaml)
-
nameis a lowercase slug and is stable across pushes. - Every value the code reads is declared in
inputswith the matchingname. - Each secret uses the right
type(api_secret/db_connection/llm_credential);where_to_getishttps://…when present.
Behaviour (norms that make an agent feel professional)
- Validate inputs and fail fast/cheap before burning an LLM call.
- Keep prompts tight — the user pays for tokens.
- Version breaking changes in the name (
my-agent-v2); don't silently change what people already installed.
4. Publish — sign in, connect GitHub, then push
a) Get the app and the CLI
Download the init app for your platform from the
Download page (Windows and Linux). The same
binary is the desktop app when opened and the init CLI from a terminal.
b) Sign in by email
Your account is your email address. Open the app (or the website) and enter it: init-store sends a six-digit code, valid for ten minutes, and you type it in. There are no passwords. From a terminal:
init login # asks for your email, then the code
This stores a credential in ~/.plw/config.json (owner-only). For CI, mint an
API token under Builder → API tokens (after connecting GitHub) and use init login --token <token>.
c) Connect GitHub
Building and sharing agents needs a GitHub account connected to your init-store
account: open Account → Connect GitHub (the app opens the page for you,
already signed in). GitHub is linked to your account; it is not a way to sign in.
Your agents are published under <your-github-login>/<agent>.
d) Push your folder
init push ./my-agent # validate, pack, upload
init push ./my-agent --dry-run # local validation only, no upload
init push validates the folder locally (manifest well-formed, inference.py
defines run()), packs your code into a bundle, and uploads it. The server
checks it again and stores it as an immutable release. There is nothing to
wait for: it answers straight away. You can do the same from the app's
Studio, which also edits and test-runs the folder on your machine.
init releases my-agent # release history, by agent name
e) Share it — agents are private by default
A new agent is private and live at once: only you, and the people you share it with, can see or install it. It is not in the store, search or any list.
Share it by email from the app's Studio (or the agent's page under Your agents on the website). Add addresses, one or several. When a person signs in with that email, on any machine, the agent appears under Shared with me in their library. The address does not need an account yet. Removing an address removes their access: their app notices and switches the agent off (their own data stays).
Sharing is access, not an endorsement: init-store does not review shared agents, and each person is told so before the first run. A shared agent runs on the recipient's machine with the recipient's own keys and model, never yours.
f) List it publicly
To put an agent in the public store, press List publicly on its page. This
is the one step that needs more than 100 stars in total across your public
repositories (forks don't count). That is the only requirement: no application,
no waiting list. Make private takes it back out of the store at any time;
anyone you shared it with keeps their access. Every init push of the same name
updates the live agent, the same way pushing to a repository does.
5. Running it (yours or a user's)
Anyone can install and run a public agent from the terminal without logging in (the desktop app asks you to sign in by email first):
init install <github-login>/<agent> # downloads the bundle
init run <github-login>/<agent> --in input.json --var OPENAI_API_KEY=sk-...
--in is a JSON file that becomes previous_output; --var KEY=VALUE supplies a
binding for the run. The app stores your keys in a vault on your computer, so you
normally set each one once.
Test your own folder before pushing it:
init run ./my-agent --in input.json --var OPENAI_API_KEY=sk-...
6. Minimal working example
hello-agent/
├── agent.yaml
└── inference.py
# agent.yaml
name: hello-agent
description: Echoes a greeting
# inference.py
def run(inputs: dict) -> dict:
name = inputs.get("previous_output", {}).get("name", "world")
return {"greeting": f"hello, {name}"}
init push ./hello-agent
7. Realistic example (BYOK + an LLM call)
summarizer/
├── agent.yaml
├── inference.py
└── requirements.txt
# agent.yaml
name: text-summarizer
description: Summarize text in 3 bullets using your own OpenAI key
runtime: python3.12
category: productivity
llm:
required: true
local_capable: true
inputs:
- name: OPENAI_API_KEY
type: api_secret
description: Your OpenAI API key
where_to_get: https://platform.openai.com/api-keys
required: true
# requirements.txt
openai==1.51.0
# inference.py
import os
from openai import OpenAI
def run(inputs: dict) -> dict:
text = inputs.get("previous_output", {}).get("text", "")
if not text.strip():
return {"error": "no text provided"}
client = OpenAI() # reads OPENAI_API_KEY (and OPENAI_BASE_URL for a local model)
resp = client.chat.completions.create(
model=os.environ.get("MODEL", "gpt-4o-mini"),
messages=[{"role": "user", "content": f"Summarize in 3 bullets:\n{text}"}],
)
return {"summary": resp.choices[0].message.content}
8. Reference
- The agent contract, step types, and the manifest in depth: docs/AGENT_STANDARDS.md.
- How the pieces fit together, and what the server does and doesn't keep: docs/ARCHITECTURE.md.
- Contributing to init-store itself: CONTRIBUTING.md.