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)

  1. Make a folder with inference.py defining def run(inputs: dict) -> dict.
  2. Add agent.yaml (a name, and what the user must supply).
  3. 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.
  4. init login once on your machine, then init push ./my-agent.
  5. 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 *.py files in the folder plus requirements.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 to inference.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):

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 as os.environ[name] and in inputs["bindings"][name]. file_url and knowledge_handle are large/structured and arrive in inputs["bindings"] only (never the environment).

Runtime environment

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:

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


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

Manifest (agent.yaml)

Behaviour (norms that make an agent feel professional)


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