Run your first agent
Start a local app, send a real signed request, and watch its character respond.
You'll run a local receiver and a separate signing agent, then see the completed request in your browser. The first task echoes your message and returns its SHA-256 digest.
You need: Node 20+, npm, and two terminal tabs. Everything uses public packages; no account or API key is required. This guide uses create-openagent 0.5.2 with @openagentid/sdk 0.7.2.
1. Start the app
Open a terminal in the folder where you keep your projects. Choose a location you can open again in a second terminal.
Copy the whole block. The last command keeps the app running.
npx --yes create-openagent@0.5.2 my-agent-app --yes
cd my-agent-app
npm install
npm run devOpen the printed viewer URL, normally http://127.0.0.1:3210. Use the numeric address exactly as printed. Keep this terminal running.
You'll see your agent's DID and its Autos character. Before a request runs, the viewer is idle with zero completed requests.
2. Send a signed request
Open a second terminal in the same parent folder you used at the start of step 1. Enter the generated project and send a message:
cd my-agent-app
npm run agent -- "Hello from my agent"If your new terminal already opened inside my-agent-app, run only the second line.
The agent requests a fresh challenge, signs it with its persisted Ed25519 key, and sends the proof to the receiver. The receiver verifies the request before returning the result.
3. See it succeed
Check both places:
- Terminal 2: the command completes successfully and prints JSON with your actual
did, the messageHello from my agent, and a 64-character hexadecimaldigest. - Browser: the same DID appears, the status becomes
success, and the completed-request count changes from 0 to 1.
These values come from your running app. Your DID and digest are generated locally; there is no example identity to substitute.
You now have a real authenticated request between a signer and a receiver. The receiver checks current trust, audience, signature and the issued nonce, then consumes the proof so it cannot be replayed.
Try another message in terminal 2:
npm run agent -- "A second request from my agent"The completed-request count increases again. In the viewer, try SpaceX or another family: appearance changes while the DID and request count stay the same. Choose Follow actual status for the expression if you want the character to reflect request status instead of a manual expression.
Make it yours
If something stops
| What you see | What to do |
|---|---|
node or npm is unavailable, or your Node version is below 20 | Install a supported Node release with npm, open a new terminal, and start at step 1. |
The generator refuses an existing my-agent-app folder | If it is the app you already created, open that folder and continue with npm install and npm run dev. Otherwise choose a different project name; keep existing files. |
cd my-agent-app cannot find the folder | Open terminal 2 in the parent folder where you generated the app. If you're already inside the project, skip that line. |
| The receiver's port is already in use | Stop an earlier instance of this starter with Ctrl+C, then run npm run dev again. If this same project is already running, use that instance's printed viewer URL. If another app owns the port, free it through that app's own controls first. |
| The agent cannot connect | Confirm terminal 1 is still running and open its printed 127.0.0.1 URL. Then retry the agent command in terminal 2. |
| The viewer stays idle with zero completed requests | Read terminal 2's error first. Confirm you're viewing the same app and that the agent command succeeded. |
| The receiver refuses the request after you revoked trust | Revocation persists. Restarting does not restore it. Keep that state; use a new project directory for a new independent walkthrough. |
| Setup reports interrupted or corrupt state | Preserve .openagent and the error. The starter refuses to replace identity state silently. Use a new project directory if you need a fresh walkthrough. |
Restart without replacing your identity
Press Ctrl+C in terminal 1, then run this from my-agent-app:
npm run devThe original DID, audience, keys and receiver trust remain. The viewer's status and completed-request counter start fresh for the new server process; appearance controls reset when the page reloads. Opening existing state never reimports trust or undoes revocation.
Keep .openagent private, backed up and on persistent storage. The generated app keeps it out of Git and serves only public viewer assets.
What the starter created
| Path | What it does |
|---|---|
src/server.mjs | Runs the loopback HTTP receiver and serves public viewer assets. |
src/agent.mjs | Requests a challenge, signs a proof and submits the authenticated request. |
src/workspaces.mjs | Creates the first-run state and reopens existing state safely. |
src/identity.mjs | Inspects the public identity and withdraws receiver trust. |
public/ | Contains the browser viewer and appearance controls. |
.openagent/signer | Holds the private signing key and local identity state. |
.openagent/receiver | Stores trusted public identities, challenges, replay and revocation state. |
.openagent/starter.json | Records the original DID and unique receiver audience. |
First-run setup exports the signer's public identity and explicitly imports it at this receiver. A submitted proof cannot enroll its own key. The public viewer is read-only; control requests still need authentication.
An identity establishes who signed. Your receiver's policy determines what they may do. The avatar is presentation, separate from both decisions.
Inspect and test the app
From my-agent-app in terminal 2:
npm test
npm run identity -- exportThe generated tests exercise real HTTP signatures, separate workspaces, restart, replay refusal, wrong audiences, unsafe requests and persisted revocation. The export command prints the public identity document.
The starter runs on one host and binds to loopback. Before exposing it to a network, follow production integration. The generator supports its working starter template; older template, bridge, adapter and deployment flags are rejected.