Skip to content

Make Developers a clean CLI and API reference #2000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
asim merged 1 commit into from
Oct 2, 2026
Merged

Make Developers a clean CLI and API reference #2000

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 31 additions & 39 deletions internal/server/developers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,54 +10,46 @@ import (

func DevelopersHandler(w http.ResponseWriter, r *http.Request) {
base := html.EscapeString(strings.TrimRight(origin.URL(r), "/"))
body := `<div class="document-content"><p>Ask an agent, assign work and retrieve the result through HTTP or the Mu CLI.</p>
<p>Micro runs the agents and tools for you. Use your account and credits; no model key or server setup is needed. If your own agent only needs tools, start with <a href="/tools">MCP tools</a> or the <a href="/api">services HTTP API</a>.</p>
<h2>Start with Micro</h2><p><a href="/account/tokens?add=api#create-token-form">Create a token</a>: choose Agents / Account, enable Agents and Background jobs, and Allow actions. Enable Inbox too if you want to read conversations. Keep the token in your environment or CLI configuration, outside browser code and source control.</p>
<p>Build the current CLI from <a href="https://github.com/micro/mu">Mu</a>, then sign in:</p><pre>git clone https://github.com/micro/mu.git
cd mu
go build -o mu .
./mu login ` + base + `
./mu ask "Compare SQLite and PostgreSQL for a small personal server"</pre>
<p>Micro returns an answer and saves the conversation. Use <code>./mu ask --raw "…"</code> for JSON containing <code>text</code> and <code>thread</code>; continue with <code>./mu ask --thread THREAD_ID "…"</code>.</p>
<h2>Assign work</h2><p>For a task that should keep running after your request returns:</p><pre>./mu work submit --prompt "Compare SQLite and PostgreSQL for a small personal server. Cite sources and recommend one."
./mu work get --id WORK_ID</pre>
<p>Submission returns an <code>id</code>. Reading it returns a <code>work</code> object with its <code>status</code>, <code>result</code>, steps and attempts. Check periodically: todo is queued, doing is running, done is complete; failed, blocked or canceled need review. The same work appears in <a href="/work">Work</a>.</p>
<h2>Create an agent</h2><p>Give an agent reusable instructions and an explicit set of services it may use:</p><pre>./mu agent create researcher \
--prompt "Research questions using sources. Cite URLs and distinguish facts from uncertainty." \
--tools web,news
./mu agent list
./mu work submit --agent researcher --prompt "Compare SQLite and PostgreSQL for a small personal server"</pre>
<p>Creation returns its <code>agent</code> name. Use that returned name when assigning work or with <code>./mu ask --agent NAME</code>. The tools flag takes service names from the <a href="/services">services directory</a>. Creating an agent does not issue another token; your plan's agent limit applies.</p>
<h2>Use HTTP</h2><p>The CLI uses these same resources. Set your token as <code>MU_TOKEN</code>, then ask Micro:</p><pre>curl '` + base + `/agent' \
body := `<div class="document-content"><p>Ask the agent, assign work or call services from your own applications.</p>
<nav class="form-actions" aria-label="Developer resources"><a href="/tools">Tools &amp; MCP</a><a href="/api">Services API</a><a href="/x402">x402</a><a href="/account/tokens">Access tokens</a></nav>
<h2>CLI</h2><p>Install Mu and connect to your account:</p><pre>curl -fsSL https://raw.githubusercontent.com/micro/mu/main/install.sh | sh
mu login ` + base + `
Comment on lines +15 to +16

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Make the post-install command reachable in the current shell

On a fresh machine where ~/.local/bin is not already in PATH, the piped installer puts mu there and exports the updated path only inside its child shell, so the immediately following mu login fails with command not found. Invoke the installed binary by its full path or tell the user to reload/source their shell before continuing.

Useful? React with 👍 / 👎.

mu ask "What needs my attention?"</pre>
<p>No model key is needed to use the hosted assistant. To continue a conversation, use <code>mu ask --thread THREAD_ID "…"</code>. Add <code>--raw</code> for JSON.</p>
<pre>mu work submit --prompt "Research the options and recommend one"
mu work get --id WORK_ID
mu inbox list
mu tools
mu help</pre>
<p>Work runs in the background; use its returned ID to read progress and the result. Use <code>mu help SERVICE METHOD</code> to see how to call a service.</p>
<h2>HTTP</h2><p><a href="/account/tokens">Create a token</a> and set it as <code>MU_TOKEN</code>. Choose Agents / Account for the agent, work and inbox; enable the permissions you need, including Allow actions to submit work.</p>
<pre>curl '` + base + `/agent' \
-H "Authorization: Bearer $MU_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"prompt":"Compare SQLite and PostgreSQL for a small personal server"}'</pre>
<p>To create an agent:</p><pre>curl '` + base + `/agents' \
-H "Authorization: Bearer $MU_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"name":"researcher","prompt":"Research using sources and cite URLs.","services":["web","news"]}'</pre>
<p>To assign work, use the returned agent name:</p><pre>curl '` + base + `/work' \
-d '{"prompt":"What needs my attention?"}'</pre>
<p>The response includes <code>text</code> and <code>thread</code>. Send <code>thread</code> with your next prompt to continue.</p>
<pre>curl '` + base + `/work' \
-H "Authorization: Bearer $MU_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"agent":"researcher","prompt":"Compare SQLite and PostgreSQL for a small personal server"}'
-H 'Content-Type: application/json' \
-d '{"prompt":"Research the options and recommend one"}'
Comment on lines +32 to +36

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Warn against replaying ambiguous work submissions

If POST /work completes server-side but the client loses the response, repeating this curl creates another durable task because the product endpoint has no idempotency key; both jobs may consume credits and repeat tool side effects. This rewrite removes the previous inspect-before-retry warning while continuing to advertise the raw POST, so restore that warning adjacent to the example or document an idempotency mechanism.

Useful? React with 👍 / 👎.


curl '` + base + `/work/WORK_ID' \
-H "Authorization: Bearer $MU_TOKEN" \
-H 'Accept: application/json'</pre>
<table class="data-table stacked"><thead><tr><th>Request</th><th>Purpose</th></tr></thead><tbody>
<tr><td>GET /agents</td><td>List your agents.</td></tr>
<tr><td>POST /agents</td><td>Create with name, prompt and a nonempty services array.</td></tr>
<tr><td>POST /agent or /agent/NAME</td><td>Ask with prompt; pass thread to continue a conversation.</td></tr>
<tr><td>POST /work</td><td>Submit prompt, optional agent and optional thread for context and delivery.</td></tr>
<tr><td>GET /work</td><td>List work; optionally filter with ?status=failed.</td></tr>
<tr><td>GET /work/WORK_ID</td><td>Read progress and result in the work field.</td></tr>
<tr><td>GET /inbox/THREAD_ID</td><td>Read the conversation, including delivered results.</td></tr>
<p>Submission returns an <code>id</code>. Reading it returns <code>work.status</code> and <code>work.result</code>. Agent replies and work use your account's credits.</p>
<table class="data-table stacked"><thead><tr><th>Resource</th><th>Use</th></tr></thead><tbody>
<tr><td><code>POST /agent</code></td><td>Ask Micro with a prompt and optional thread.</td></tr>
<tr><td><code>POST /agent/NAME</code></td><td>Ask a specific agent.</td></tr>
<tr><td><code>GET /agents</code></td><td>List your agents.</td></tr>

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document content negotiation for every listed read

A bearer-authenticated client following a table-only entry such as GET /agents without Accept: application/json receives the HTML resource because these handlers select JSON through content negotiation. The curl examples do not cover /agents or /inbox, and this change removes the previous global header requirement, so restore an explicit Accept: application/json instruction beside the table.

AGENTS.md reference: AGENTS.md:L16-L18

Useful? React with 👍 / 👎.

<tr><td><code>POST /work</code></td><td>Assign a prompt, with an optional agent and thread.</td></tr>
<tr><td><code>GET /work</code></td><td>List your work.</td></tr>
<tr><td><code>GET /work/WORK_ID</code></td><td>Read progress and results.</td></tr>
<tr><td><code>GET /inbox/THREAD_ID</code></td><td>Read a conversation.</td></tr>
</tbody></table>
<p>Existing ?id= links remain supported. Path, query and body IDs must agree when supplied together. JSON and URL-encoded form bodies are accepted for actions; Accept selects the response format. Single-work reads retain the work field; conversation reads retain thread and messages, whichever URL is used.</p><p>All calls require your token and Accept: application/json; JSON POST requests also require Content-Type: application/json. Usage draws from the same account allowance and balance. After a lost creation or submission response, inspect your agents or work before retrying. To retry reviewed work explicitly, use <code>./mu work retry --id WORK_ID</code> or POST /work with <code>{"action":"retry","id":"WORK_ID"}</code>; previous actions may be repeated.</p>
<h2>Hosted or self-hosted</h2><p>The CLI defaults to Micro. Run <code>./mu login https://your-server.example</code> to use your own Mu server, or set <code>MU_URL</code> and <code>MU_TOKEN</code>. The HTTP resources stay the same; a self-hosted server needs its own model and service configuration. See <a href="/install">self-hosting</a>.</p>
<h2>Tools and x402</h2><p>Bring your own agent to <a href="/tools">/mcp</a> or the <a href="/api">services API</a> to call individual tools with a Services token. For wallet-paid public service calls, use <a href="/x402">x402</a>: m3o.com is the machine-readable endpoint. Hosted agent execution uses your Micro account and credits.</p></div>`
<h2>Services and tools</h2><p>Call services directly with a Services token. The <a href="/api">API reference</a> lists HTTP endpoints, parameters and examples. The <a href="/tools">Tools page</a> lists MCP tools and connection instructions for your own agent. In the CLI, use <code>mu tools</code> to discover them and <code>mu SERVICE METHOD --argument value</code> to call one.</p>
<h2>Pay per call</h2><p><a href="/x402">x402</a> lets your applications pay for public service calls with USDC. See the payment and connection details there.</p>
<h2>Self-hosting</h2><p>The same CLI works with your own server: <code>mu login https://your-server.example</code>. See the <a href="/install">installation guide</a> and <a href="https://github.com/micro/mu">source code</a>.</p></div>`
app.Respond(w, r, app.Response{Title: "Developers", HTML: body})
}
Loading