Run the agent starter
Install the agent template, configure its model channels, sandbox and search providers, start the agent service and open the workbench.
The agent-starter template adds an Agent workbench and a separate Node service. The service coordinates runs, approvals, user requests, skills, tools and a per-run workspace. Model calls use configured AI channels, and the server reserves and settles credits. The agent is optional. A deployment without the service is still a complete web app, and its agent entries show that the service is not deployed. This guide covers installation and readiness. See Agent runtime for the execution model.
What the template adds
| Part | Where it lives |
|---|---|
| Agent contracts, run loop, tools and browser client | packages/agent-{contracts,runtime,tools,client} |
| Sandbox provider and its image | packages/sandbox-adapter, packages/sandbox-adapter/template/Dockerfile |
| The agent service, a second process | apps/agent-service |
| Runs, threads, messages, skills, approvals, workspaces and background tasks | migration 0016_agent_starter, SQLite and Postgres |
| Authenticated API for the browser | /api/agent/** |
| Workbench | /app/agent |
The agent-starter plugin: its navigation entries and route ownership | src/plugins/agent-starter |
| Provider configuration | /admin/config/sandbox, /admin/config/search |
| Platform skills and their publisher | agent-skills/, pnpm agent:publish-skills |
| Its validators | pnpm validate:agent-starter, validate:optional-agent, validate:dsh-runtime, validate:agent-plugin-contract, validate:sqlite-transactions, validate:agent-generation |
The workbench requires a usable agent.general model route and configured sandbox. Search and crawl providers are required only for tools that use them. The workbench reports missing configuration and never simulates a provider response.
Before you begin
- The base repository, or the
image-agentorvideo-agentbusiness template. The agent stack is part of each. See Get Kernlift. - Node 20 or later, and a project that runs locally. See Quick start.
- Postgres, or SQLite on Node. Agent runs need interactive transactions, which Cloudflare D1
does not have. On D1 the web application runs as usual, the agent entries are hidden and
/api/agent/*answers503 agent_unavailable. See Use Postgres and Supabase. - An administrator account holding
config.readandconfig.write. The two configuration pages the template adds use the permissions the console already has, so there is nothing new to grant. - Object storage configured in
/admin/config/storage. Skill bundles, run artifacts and workspace files are stored there. Until it is configuredpnpm agent:publish-skillspublishes nothing and prints the reason.pnpm dev:agentprints the same message and still starts both processes, so the configuration page stays reachable. See Set up file storage and uploads. - An E2B-compatible sandbox service, if the agent is to execute scripts, and a SearXNG and crawl4ai deployment if it is to search and read pages.
Set up the agent service
Install packages and migrate
pnpm install && pnpm db:migrateThe agent stack is already in the repository: workspace packages under packages/agent-* and a
separate app in apps/agent-service. pnpm install installs their dependencies, and the migration
creates the Agent tables for the configured dialect. Both are no-ops if you ran them in the quick start.
Point the two processes at each other
# Infrastructure only. Providers, limits and prices are configured in /admin/config/*.
AGENT_SERVICE_URL=http://127.0.0.1:3001
AGENT_WEB_INTERNAL_URL=http://127.0.0.1:5173
AGENT_INTERNAL_SIGNING_SECRET=
AGENT_RESOURCE_GRANT_SECRET=Run openssl rand -hex 32 twice. Put the two independently generated values in the blank secret fields and use the same pair in the corresponding fields of both processes.
AGENT_SERVICE_HOST, AGENT_SERVICE_PORT, AGENT_SERVICE_REQUEST_TIMEOUT_MS,
AGENT_FLOW_LOG_LEVEL and AGENT_SANDBOX_ERROR_LOG_ENABLED are optional, and .env.example lists
them with their defaults. No provider credential belongs in either environment. These variables
are needed only when you run the agent. Without AGENT_SERVICE_URL and the signing secret the web
app treats the agent as not deployed.
Two processes
The web application serves the pages, authenticates every /api/agent/** request and forwards it.
apps/agent-service is a Node process that runs the agent loop, the sandboxes and the background
worker. They communicate over signed HTTP, using the two secrets above. The signing
secret authenticates a request between them, and the resource grant secret signs the short-lived
tokens a sandbox uses to reach a file or a model.
For local work, pnpm dev runs the web application alone and one command runs both:
pnpm dev:agentIt migrates the database, publishes the platform skills, builds the attachment parser, then runs
Vite and the agent service together. When either secret is unset or shorter than 32 bytes it
generates one for the session, so a first run needs no secret management. A project that has not
configured object storage yet publishes no skill. The command prints a message and starts both processes
so that /admin/config/storage remains available for setup.
Prepare sandbox and retrieval services
| Provider | Choose it for |
|---|---|
| E2B | Execute scripts in an E2B runner |
| Alibaba Cloud Sandbox | Use an Alibaba Cloud runner image |
| Novita Sandbox | Use an existing Novita sandbox |
| SearXNG | Search through a self-hosted instance |
| Crawl4AI | Extract content from a web page |
Configure the providers
Model channels
Open /admin/config/ai and give each agent scene an active route: agent.general for ordinary
conversation, agent.research for search-led runs, agent.mail for the mail assistant and
agent.audio for speech. A scene without an active channel is reported as not configured, and a
run that needs it fails with that message. See
Configure AI scenes.
Sandbox
Open /admin/config/sandbox, enable it, choose the provider and its control-plane URL, set the
runner template and the runtime limits, and paste the provider key. The key is write-only. It is
stored in the admin config table and never shown again. There is no E2B_* environment fallback.
A sandbox without configuration is reported as unavailable, and script tools return an error.
packages/sandbox-adapter/template/Dockerfile is the image the runner template is
built from.
Search
Open /admin/config/search for SearXNG (search) and crawl4ai (page extraction). Each has its own
base URL, authentication header, timeout and enable switch, and a Test connection button that
performs a real request against the service you named.
Platform skills
agent-skills/ holds the skills the agent may load: general-chat and mail-assistant. An
installed capability plugin, such as the image agent, keeps its skill in its own plugin folder and
is published by the same command.
pnpm agent:publish-skillsThe command bundles each one and publishes it to the skill registry, skipping any whose content is
already the active version. A run loads skills from the registry and does not read the files on disk, so
publish after editing them and as part of every deploy. agent-skills/ is separate from skills/, which is
this repository's documentation for coding agents.
Open the workbench
With both processes running, sign in and open /app/agent. Threads, the streaming conversation,
approvals and the artifacts panel are all on that page. Before the providers above are configured
it shows the missing configuration and disables unavailable actions.
Deploy
The two processes deploy separately, and the web application must be able to reach the service.
The agent service
Build the bundle and run it on Node 22 or later, directly or in a container:
pnpm build:agent-service
node apps/agent-service/dist/main.jsGive it the database connection, AGENT_INTERNAL_SIGNING_SECRET, AGENT_RESOURCE_GRANT_SECRET,
AGENT_WEB_INTERNAL_URL and its listen address. The process refuses to start
when an authentication or payment secret is present in its environment (BETTER_AUTH_*, AUTH_*,
STRIPE_*, PAYMENT_* and the like), because it runs untrusted code in sandboxes and must not
hold them. The same build writes dist/publish-skills.mjs, which a deploy runs for
the skill publish step.
The web application
Deploy it as you already do, with one constraint: its database must be the one holding the agent
tables, so D1 cannot serve them. Set AGENT_SERVICE_URL to the service's internal address and
keep the service off the public internet. The browser never connects to it directly.
On Cloudflare the agent service runs as a container next to the Worker. The Worker reaches
Postgres through Hyperdrive (DATABASE_DIALECT=postgres, DATABASE_ADAPTER=hyperdrive), the
container connects directly with AGENT_DATABASE_URL, and the AGENT_SERVICE binding replaces
AGENT_SERVICE_URL. The commented blocks in wrangler.jsonc list the steps. See
Deploy to Cloudflare Workers,
Deploy to a Node host and the Fly.io, Railway and Docker guides, each
of which runs the agent as a separate service.
After each deploy
pnpm db:migrate
pnpm agent:publish-skillsBoth are idempotent. A deploy that changed no migration and no skill writes nothing.
Verify
pnpm db:migratereports0016_agent_starterapplied, in the dialect you deploy./admin/config/sandboxshows the sandbox as configured, with the key held in the admin config table and not shown on the page./admin/config/searchreports a successful test connection for each provider you enabled.curl -i http://127.0.0.1:5173/api/agent/threadswithout a session answers401. Signed in, it returns only your own threads.- The agent service answers
GET /healthzwithstatus: "ok", andGET /readyzanswers200withdatabase,schema,objectStorageandprovidersallreadyonce the scenes and the sandbox are configured. /app/agentruns a turn end to end, and the run's credit reservation appears as a captured entry in the credit ledger.
In the repository, run pnpm validate:agent-starter and pnpm validate:optional-agent.
Troubleshooting
The Agent entry is missing, or /api/agent/* answers 503
The web app reports the agent as unavailable. The response carries the code agent_unavailable
and an x-agent-unavailable-reason header:
| Reason | Fix |
|---|---|
plugin_disabled | Switch agent-starter on in Settings → Plugins. |
database_not_transactional | The database is D1. Use Postgres, or SQLite on Node. |
service_not_configured | Set AGENT_SERVICE_URL, or on Cloudflare add the AGENT_SERVICE container binding. |
signing_secret_missing | Set AGENT_INTERNAL_SIGNING_SECRET to the same value in both processes. |
/app/agent shows the same reason to an administrator.
An agent script fails with agent_requires_transactions
The process is connected to a database without interactive transactions (D1). Point it at
Postgres (DATABASE_DIALECT=postgres) or at SQLite on Node. The script fails before it writes anything,
so there is nothing to clean up.
A run fails saying the model is not configured
The scene the run needs has no active channel route. Configure it in /admin/config/ai. /readyz
reports providers: not_ready until every active route resolves to a channel that has its
credential.
A script tool refuses with the sandbox unconfigured
/admin/config/sandbox is disabled or its key is missing. There is no environment fallback, so
saving the key there is the only way to configure it.
The service exits with forbidden_agent_service_configuration
Its environment carries an authentication or payment secret. Remove it. The service needs only the database, the two agent secrets and the internal web URL.
pnpm agent:publish-skills reports that object storage is not configured
A bundle is stored in object storage, so nothing can be published until /admin/config/storage
has a provider. The command exits non-zero, so a deploy that runs it stops. pnpm dev:agent prints
the same message and starts both processes so the page can be reached. Configure it, then run the
publish again.
A new skill has no effect on a run
The skill was changed on disk but not published. Run pnpm agent:publish-skills. Runs read skills from the
registry, not from agent-skills/.