Quickstart

This page takes the blank template from an empty folder to an app people can open in your workspace.

Before you start

Install the Agent Serve CLI and sign in with agentserve login.
Have Bun or Node.js 20 or later for the app's build.
To publish and install, you need the admin role in the workspace. Uploading a draft needs write. See Roles.

Create the app

agentserve app init my-app
cd my-app
bun install   # or: npm install

init copies the blank template into my-app, sets the manifest name to my-app (from the folder name) and its title to My app, and copies the app SDK into vendor/app-sdk. It refuses a folder that is not empty unless you pass --force.

To start from another template, pass --template. agentserve app init --list prints them all. See Templates.

The folder now holds:

my-app/
├── agentserve.app.yaml   # the manifest
├── index.html
├── package.json
├── src/                  # your React code
├── tables/items.yaml     # a table the install creates
├── vendor/app-sdk/       # the SDK, copied by init
└── vite.config.ts        # builds into dist/

Run it locally

agentserve app dev

dev builds the app and serves it at http://localhost:5175, inside a local host page that frames it with the same sandbox and content security policy as the workspace. SDK calls go to your workspace through the API with your own CLI login, so the app sees exactly what you can see, still narrowed to what the manifest names.

When you change a file, dev rebuilds and reloads the frame. It ignores dist/, node_modules/ and vendor/.

The blank app reads a table called items. Until you install the app, that table only exists if you create it yourself, so the items card shows an error. Everything else works.

A few calls behave differently in dev; see agentserve app dev.

Deploy a draft

agentserve app deploy

deploy runs the build, packs the manifest, the folders your pages live in (here dist/), the icon, the files under requires and any code tools into a .zip, and uploads it as a draft version. It prints the version, 0.1.0, and a link to the app's versions page in the workspace.

A draft cannot be installed yet. Each upload needs a new version in the manifest; uploading a version that already exists fails.

Publish the version

agentserve app publish 0.1.0

Publishing makes the draft installable. It needs the admin role.

Install it

agentserve app install

install installs the highest published version in your current workspace (pass -w <workspace> for another one). It prints what it created — here the items table — and anything it skipped.

Open it

In the workspace, open Apps in the left rail and pick My app (the title init made from the folder name; pass --title to choose another). On the app's Manage page an admin can pin it to the rail for chosen roles or groups, set a monthly budget, and see spend and activity.

Ship a change

Edit the code and raise version in agentserve.app.yaml, for example to 0.2.0.
Deploy and publish, moving your workspace's install to the new version in one step:
```
agentserve app deploy
agentserve app publish 0.2.0 --rollout
```
If something is wrong, move back: agentserve app rollback 0.1.0.

Next steps

Add permissions and pages: Manifest reference.
Call workflows, Relays and Chat from your code: App SDK.
Understand what admins approve: Security model.

Quickstart

On this page