Deploy your first agent

This guide uses the public Stead service and npm packages. You need Node.js 22 or newer, npm, a verification inbox, and a funded provider API key. You do not need to create infrastructure accounts or a database.

1. Create your developer account

Open the developer console, create an account, and follow the verification email. Return to the console and sign in.

This account owns your projects. You will create a separate customer account inside the demo app later.

2. Create the starter

Run this from a directory where my-agent does not already contain a starter:

npx --yes getstead@0.2.1 init my-agent
cd my-agent

The starter contains stead.json, handlers.mjs, SQL migrations, CLI scenarios, and a React application in web/.

3. Sign in and create a project

npx --yes getstead@0.2.1 login --api-url https://api.getstead.dev

Open the displayed browser link. Check that the code on the page matches your terminal, enter that code, and authorize the terminal. Only authorize a login you started yourself.

Then create your project:

npx --yes getstead@0.2.1 projects create "My first agent"

The CLI selects the project in stead.json and displays its project credential once. Treat that credential as a secret. The remaining steps use your developer login, so you do not need to paste the credential into an environment file or browser app.

4. Configure the provider and browser origin

In the console, open My first agent → Settings.

• Save your model provider key. For the default starter, use the base URL https://api.openai.com/v1 and a key with access to gpt-5.6-luna.
• Add http://localhost:5173 to the allowed browser origins and save it.

Use the exact origin, including the port. http://127.0.0.1:5173 is a different origin. The provider key belongs in project settings; never put it in a VITE_ variable or frontend code.

5. Deploy

npx --yes getstead@0.2.1 deploy
npx --yes getstead@0.2.1 doctor

The first deployment provisions the project’s isolated database, applies 0001_orders.sql, and stores the handler bundle and three agents: support-agent, demo-orders, and refund-order.

doctor should show a deployed agent configuration and a ready project database. Notices describe limits; they are not necessarily failures. If your provider key or credit needs checking, this optional command makes a small billable model request:

npx --yes getstead@0.2.1 doctor --check-provider

6. Start the customer app

cd web
npm install
npm run dev

Open http://localhost:5173. The app reads the selected project ID and API URL from stead.json; no frontend secret is required.

Choose Create account, register a customer, follow its verification email, and sign in to the app. You may use the same email as your developer account, but this is a separate registration and password.

If port 5173 is in use, stop the other development server or follow the browser-origin troubleshooting steps to choose a different port consistently.

7. Read private data

Click Create demo orders, then ask:

What orders do I have, and how much did each cost?

The app should show a Trail backpack for $89 and a Travel mug for $24. The agent reads this customer’s order data before asking the model to answer. A different customer does not share these orders.

The model response is billable through your provider. The starter’s limits are described on Try Stead.

8. Approve an action

In the customer app, click Request refund for Travel mug. The run should wait for approval while the mug’s balance stays at $24.

Switch to your developer console, open the project’s Approvals page, inspect the action, and choose Approve action. The customer app should update to $0.00 · Refunded without another refund request.

This changes a demo database balance. It does not issue a payment refund. Choosing Deny action prevents the tool from running.

9. Return to the conversation

Sign out of the customer app, then sign back in. Your orders and conversation should remain available. The starter keeps its login session in project-scoped sessionStorage; logging out clears the local session.

In the console, inspect Runs to see step results, approvals, errors, and reported usage. Keep tokens, keys, private tool results, and customer messages out of shared screenshots.

Next steps

Change the handlers and agent configuration, then run npx getstead deploy again from the project root. Add new migration files for schema changes instead of editing an already-applied migration.

Use the integration guide to connect your own app, or troubleshooting if any step failed.