agentserve app

The agentserve app commands take an app from an empty folder to an install people use, and help you operate it afterwards. Sign in first with agentserve login; see Authentication. Every flag of every command is in the generated CLI reference.

Choosing the app and workspace

Commands that act on an app that already exists pick it in this order:

1. --app <name-or-id>, when you pass it.
2. The name in ./agentserve.app.yaml, when you run the command in the app's folder.

The usual global options apply: -P, --profile picks a login profile, -w, --workspace a workspace, and --output the output format. Every app command also takes --json, which prints one machine-readable JSON document instead of text.

Exit codes

agentserve app init

agentserve app init [dir] [--template <name>] [--name <slug>] [--title <text>] [--force]
agentserve app init --list

Creates an app from a template in dir (default: the current folder).

init also copies the app SDK into vendor/app-sdk. Then install the dependencies:

cd my-app
bun install   # or: npm install

agentserve app dev

agentserve app dev [dir] [--port <n>] [--page <id>] [--build-command <cmd>] [--no-build] [--no-open]

Builds the app and serves it at http://localhost:5175 in a local host page. The host page frames the app with the same sandbox and content security policy as the workspace, so what works in dev works when installed.

SDK calls are forwarded to your workspace through the API with your own CLI login. The app sees exactly what you can see, and the manifest still limits which tables, workflows and Relays it may name. When files change, dev rebuilds and reloads the frame; it ignores dist/, node_modules/ and vendor/.

Differences from an installed app:

• askChat shows the prompt in the host page instead of opening Chat.
• getViewer() returns your profile's workspace, the manifest's name, version and permissions, and placeholders for the rest: dev for the user, app, install and version ids, no name or email, and the role write.
• runTool and listTools use the version of your app installed in the workspace, because code tools run only on Agent Serve. Your local tools/ files are not used until you deploy, publish and install them. With no installed version that ships tools, both fail with not_found and a message saying how to install one.
• assignRelayTask and queryModel go through the same API endpoints a script would use, POST /api/v2/relays/tasks and POST /api/v2/semantic-model/query, as you.

dev needs an OAuth login or a personal API key: the model, Relay and code tool calls refuse a workspace API key.

agentserve app deploy

agentserve app deploy [dir] [--build-command <cmd>] [--no-build] [--json]

Runs the build, packs the app into a .zip, and uploads it as a draft version. The archive holds the manifest, the folders your pages, panels and Chat cards live in (such as dist/), the icon, the files requires names, and the code tool files tools names. It prints the version and a link to the app's versions page in the workspace.

The first deploy of a new name creates the app. Each later deploy needs a new version in the manifest; deploying a version that already exists fails. Uploading needs the write role.

Archive limits:

Files the tools globs name may also be TypeScript, JavaScript or Python sources (ts, mts, js, mjs, py). They are stored with the version and never served to the app's frame. See Code tools.

To build on Agent Serve from a repository instead, see Deploying from Git.

agentserve app publish

agentserve app publish <version> [--app <name-or-id>] [--rollout] [--json]

Makes a draft version installable. Needs the admin role. With --rollout, this workspace's install also moves to the version.

agentserve app rollback

agentserve app rollback <version> [--app <name-or-id>] [--json]

Moves this workspace's install back to an earlier published version. Needs the admin role.

agentserve app install

agentserve app install [--app <name-or-id>] [--to-version <version>] [-w <workspace>]

Installs the highest published version, or the one --to-version names, in the workspace. It prints the tables, rules and Relays it created, the ones the workspace already had, and the ones it skipped with the reason. Needs the admin role.

agentserve app logs

agentserve app logs [--app <name-or-id>] [--follow] [--interval <seconds>] [--json]

Prints the install's audit trail, newest last: version changes, secret changes and every write the app made. --follow keeps polling for new entries, every --interval seconds. Needs the admin role.

agentserve app usage

agentserve app usage [--app <name-or-id>] [--json]

Prints this month's spend against the install's budget, broken down by source. Needs the admin role.

agentserve app permissions

agentserve app permissions [dir] [--app <name-or-id>] [--json]

Prints what the installed version may reach, next to the latest uploaded version and, in an app folder, the local manifest. Differences from the install are highlighted, so you can see what a new version would add or remove before you publish it.

agentserve app secrets

agentserve app secrets set <name> [--value <text|@file|@->]
agentserve app secrets list
agentserve app secrets delete <name>

Manages the install's write-only secrets. Needs the admin role.

• set stores a value. --value takes the text itself, @path to read a file, or @- to read standard input. Without --value, it prompts for the value without showing what you type.
• list prints each secret's name and when it last changed, never its value.
• delete removes a secret.

See Secrets for the naming rules and what secrets are used for today.

A release, end to end

# In the app folder, after raising version to 0.3.0
agentserve app deploy
agentserve app permissions        # check what changes for admins
agentserve app publish 0.3.0 --rollout
agentserve app logs --follow