blog: add Build an Agent App — turn your API into an installable Pilot app (#91)

src/data/blogPosts.json

@@ -1,4 +1,19 @@
 [
+ {
+  "slug": "build-an-agent-app",
+  "title": "Build an Agent App: Turn Your API Into an Installable Pilot App",
+  "description": "Turn an existing API into an agent-installable app on Pilot Protocol — the publish flow, the discover→install→call loop, and what makes it get reused.",
+  "date": "Jul 7",
+  "category": "Blog",
+  "tags": [
+   "app-store",
+   "publish",
+   "how-to",
+   "agents"
+  ],
+  "banner": "banners/build-an-agent-app.svg",
+  "iso_date": "2026-07-07"
+ },
  {
   "slug": "build-agent-app-turn-api-into-tool",
   "title": "How to Build an Agent App: Turn Your API Into an Agent-Native Tool",

src/pages/blog/ai-agent-app-store.astro

@@ -69,7 +69,7 @@ const bodyContent = `<p>An AI agent with a network can reach other agents. An AI
   <section>
   <h2>Publish your own app</h2>
   <p>The store grows by builders adding to it, and you don't have to hand over code to do it. Through the publish flow you describe your existing app or API's methods; Pilot generates and signs an agent-first adapter for it, the team reviews it onto the store, and from then on any agent can install it with one command. Your secrets stay yours — operators supply them at install time, not you at publish time.</p>
-  <p>The shape is "bring your existing app; agents do the rest." Every published app is one more reason for an agent to be on Pilot. See <a href="/blog/build-agent-app-turn-api-into-tool">how to turn an existing API into an agent app</a> for the concrete steps.</p>
+  <p>The shape is "bring your existing app; agents do the rest." Every published app is one more reason for an agent to be on Pilot. See <a href="/blog/build-agent-app-turn-api-into-tool">how to turn an existing API into an agent app</a> for the concrete steps, and <a href="build-an-agent-app">Build an Agent App: Turn Your API Into an Installable Pilot App</a> for the full publish walkthrough, including what makes an app worth installing.</p>
   </section>
 
   <section>

src/pages/blog/build-an-agent-app.astro

@@ -0,0 +1,116 @@
+---
+import BlogLayout from '../../layouts/BlogLayout.astro';
+
+const bodyContent = `<p>You already have an API. Maybe it's a search index, a data-enrichment service, a deploy pipeline, a payments backend. The problem isn't the API — it's that every agent framework wants tools wired up differently: one expects an MCP server, another wants a REST wrapper with an OpenAPI spec, a third wants a hand-rolled function-calling schema. Multiply that by every agent that might want to use your service, and "integrate with agents" turns into a maintenance job nobody signed up for.</p>
+
+  <p>Turning your API into an agent app flips that. You describe your methods once, Pilot Protocol generates and signs an agent-first adapter for it, and from then on any agent on the network installs it with a single command and calls it the same way it calls every other app: JSON in, JSON out. This article walks through what an agent app actually is, the discover → install → call loop your users will run, how to get your own API onto the store, and what makes an app worth installing in the first place.</p>
+
+  <section>
+  <h2>Why "just add an MCP server" isn't the whole answer</h2>
+  <p>MCP standardizes how a single agent talks to the tools it already knows about — you stand up a server, the agent's client connects to it, and the agent calls your tools over that connection. That's a real, useful pattern, and Pilot works alongside it (see <a href="mcp-plus-pilot-tools-and-network">MCP + Pilot: Tools and a Network for AI Agents</a> for how the two compose). But it solves distribution for exactly the agents that already know your server exists and are configured to reach it.</p>
+  <p>An agent app on the Pilot app store solves distribution for agents that have never heard of you. It's published once to a shared, signed catalogue that any of the <strong>243k+</strong> agents on the network can browse, install, and start calling — no config file to hand-edit, no server address to discover out of band. Publishing once and reaching every agent is the whole point.</p>
+  </section>
+
+  <section>
+  <h2>What an agent app actually is</h2>
+  <p>Structurally, an installed app is a small binary plus a signed manifest, supervised by the agent's own <code>pilot-daemon</code>. The daemon fetches the bundle from the catalogue, verifies its signature and hash, requests the permissions the manifest declares (network access, file access — whatever your backend needs), and keeps the process running once it's up. Every method the app exposes is a typed call: a JSON request in, a JSON response out. There's no SDK to import and no bespoke glue code per agent.</p>
+  <p>Critically, the installed binary is a thin adapter, not your whole service. Your actual backend — the index, the model, the queue, the database — stays exactly where it already lives. The adapter just translates the daemon's typed calls into whatever your API already understands, and translates your API's response back into the JSON shape an agent expects.</p>
+  </section>
+
+  <section>
+  <h2>The loop every agent runs: discover → install → call</h2>
+  <p>Whatever app a user installs, the sequence is identical — that consistency is what makes your app cheap to adopt.</p>
+
+  <h3>1. Discover</h3>
+  <p>An agent (or the human operating it) browses the signed catalogue and can inspect any app's description, methods, and permissions before installing anything.</p>
+  <pre><code><span class="comment"># See what's installable</span>
+<span class="cmd">pilotctl appstore catalogue</span>
+
+<span class="comment"># Inspect one app before committing: vendor, methods, permissions, source</span>
+<span class="cmd">pilotctl appstore view io.pilot.cosift</span></code></pre>
+
+  <h3>2. Install</h3>
+  <p>Installing by id fetches the bundle, verifies it against the signature pinned in the manifest, prompts for the declared permission grants, and auto-spawns the process.</p>
+  <pre><code><span class="cmd">pilotctl appstore install io.pilot.cosift</span>
+<span class="cmd">pilotctl appstore list</span>   <span class="comment"># confirm it's running + see its methods</span></code></pre>
+
+  <h3>3. Call</h3>
+  <p>Every app follows a help convention — <code>&lt;app&gt;.help</code> returns its methods, parameters, and a latency class, so an agent can learn your interface at runtime instead of reading a doc page first.</p>
+  <pre><code><span class="comment"># Learn the interface at runtime</span>
+<span class="cmd">pilotctl appstore call io.pilot.cosift cosift.help '{}'</span>
+
+<span class="comment"># Call it — JSON in, JSON out</span>
+<span class="cmd">pilotctl appstore call io.pilot.cosift cosift.search '{"q":"raft consensus","k":"5"}'</span></code></pre>
+  <p>That's the entire lifecycle from an agent's side. No API key to provision by hand, no endpoint to look up — the agent discovers the method and calls it, the same way every time, for every app in the store.</p>
+  </section>
+
+  <section>
+  <h2>Getting your API onto the store</h2>
+  <p>You don't hand over your codebase to publish. The <a href="https://pilotprotocol.network/publish">publish flow</a> is a guided form: describe your app's methods, verify your email with a one-time code, and Pilot generates and signs the adapter for you from that description. There's no upload step — you're describing behavior, not shipping source.</p>
+  <p>Concretely, the flow moves through a handful of steps: your email, basic identity for the listing, where your backend lives, the methods you want exposed (name, parameters, what each one returns), the public listing details (description, category), vendor info, and a final review where you confirm you have the right to publish the app before it's submitted. Your team reviews every submission before it goes live in the catalogue — you'll get an email when it's submitted and again when it's approved or needs changes.</p>
+  <p>Two things worth planning for before you start the form:</p>
+  <ul>
+    <li><strong>Your secrets never go in the form.</strong> If your API needs an API key or a database credential, that's supplied by the operator at install time, not by you at publish time. Design your methods so every call is self-contained given the caller's own credentials, not a shared secret baked into the adapter.</li>
+    <li><strong>Write your methods like a help page, not an internal spec.</strong> Whatever description you give a method becomes what an agent reads at runtime via <code>&lt;app&gt;.help</code> — an agent has no other documentation to fall back on, so ambiguous parameter names or missing units cost you real usage.</li>
+  </ul>
+  </section>
+
+  <section>
+  <h2>What makes an app worth installing</h2>
+  <p>The apps that get reused share a few properties, visible in what's already live in the catalogue — AEGIS (a runtime firewall against prompt injection), cosift (grounded search and retrieval), sixtyfour (contact and company intelligence), miren (deploy and roll back a PaaS), smolmachines (disposable hardware-isolated microVMs), and wallet (on-overlay USDC payments), among others:</p>
+  <ul>
+    <li><strong>One job, done well.</strong> Each of these does one thing an agent needs — search, deploy, isolate, pay — rather than bundling a dozen loosely related methods behind one app id.</li>
+    <li><strong>Stateless calls.</strong> A method call shouldn't depend on some prior call having set up hidden state on the same connection; each call carries what it needs.</li>
+    <li><strong>Predictable JSON shapes.</strong> Consistent field names and types across methods let an agent generalize from one method's help text to the next, instead of parsing bespoke responses per call.</li>
+    <li><strong>A tight permission ask.</strong> Only request the network or file grants your methods actually use — a narrow ask is also a faster install decision for a cautious operator.</li>
+  </ul>
+  </section>
+
+  <section>
+  <h2>Why the store compounds for builders</h2>
+  <p>Every app published to the store is one more reason for an agent to be on Pilot at all, and one more thing an agent already on the network can reach without you doing any per-agent onboarding. That's the flywheel: publish once, and every agent that installs your app is a user you didn't have to individually integrate. Combine that with a network layer already handling <a href="ai-agent-discovery-process-p2p-networks">discovery</a>, <a href="secure-ai-agent-communication-zero-trust">trust</a>, and <a href="connect-ai-agents-behind-nat-without-vpn">NAT traversal</a> for you, and shipping an agent app is closer to "describe it once" than "build a new integration surface."</p>
+  <p>If you're standing up the network side first, start with the one-command install and a running daemon, then come back to publish once you have an agent to test against:</p>
+  <pre><code><span class="cmd">curl -fsSL https://pilotprotocol.network/install.sh | sh</span></code></pre>
+  <p>From there, <code>pilotctl appstore catalogue</code> shows you what's already installable, and <a href="https://pilotprotocol.network/publish">the publish flow</a> is how your own app joins that list.</p>
+  </section>
+
+  <div class="cta">
+    <h3>Publish your app</h3>
+    <p>Describe your API's methods once — Pilot builds and signs the adapter, and any agent can install it.</p>
+    <a href="https://pilotprotocol.network/publish">Start the publish flow</a>
+  </div>`;
+
+const faqItems = [
+  {
+    question: "How do I turn my API into an agent app on Pilot Protocol?",
+    answer: "Use the publish flow at pilotprotocol.network/publish: describe your app's methods, verify your email, and Pilot generates and signs an agent-first adapter for you. There's no code upload. The team reviews the submission before it goes live, and secrets are supplied by operators at install time, not collected from you at publish time.",
+  },
+  {
+    question: "Do I need to give Pilot my source code to publish an app?",
+    answer: "No. You describe your app's methods (name, parameters, what each returns) through the publish form, and Pilot generates and signs the adapter from that description. Your backend keeps running wherever it already lives.",
+  },
+  {
+    question: "What does an agent do to use a published app?",
+    answer: "Three steps: pilotctl appstore catalogue to browse and pilotctl appstore view <id> to inspect it, pilotctl appstore install <id> to install and auto-spawn it, then pilotctl appstore call <id> <method> '{...}' to invoke a method with a JSON request and get a JSON response back.",
+  },
+  {
+    question: "How is publishing an agent app different from building an MCP server?",
+    answer: "An MCP server is reached by agents already configured to connect to it. A Pilot agent app is published once to a shared, signed catalogue that any agent on the network can discover and install with one command — the two are complementary, and you can offer both.",
+  },
+  {
+    question: "Who supplies API keys or credentials for a published app?",
+    answer: "The operator installing the app, at install time — not the publisher, and not at publish time. Design your app's methods so each call is self-contained given the caller's own credentials rather than a shared secret baked into the adapter.",
+  },
+];
+---
+<BlogLayout
+  title="Build an Agent App: Turn Your API Into an Installable Pilot App"
+  description="Turn an existing API into an agent-installable app on Pilot Protocol — the publish flow, the discover→install→call loop, and what makes it get reused."
+  date="July 7, 2026"
+  tags={["app-store", "publish", "how-to", "agents"]}
+  canonicalPath="/blog/build-an-agent-app"
+  bannerImage="/blog/banners/build-an-agent-app.svg"
+  faqItems={faqItems}
+>
+  <Fragment set:html={bodyContent} />
+</BlogLayout>