Kernlift

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

PartWhere it lives
Agent contracts, run loop, tools and browser clientpackages/agent-{contracts,runtime,tools,client}
Sandbox provider and its imagepackages/sandbox-adapter, packages/sandbox-adapter/template/Dockerfile
The agent service, a second processapps/agent-service
Runs, threads, messages, skills, approvals, workspaces and background tasksmigration 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 ownershipsrc/plugins/agent-starter
Provider configuration/admin/config/sandbox, /admin/config/search
Platform skills and their publisheragent-skills/, pnpm agent:publish-skills
Its validatorspnpm 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-agent or video-agent business 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/* answers 503 agent_unavailable. See Use Postgres and Supabase.
  • An administrator account holding config.read and config.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 configured pnpm agent:publish-skills publishes nothing and prints the reason. pnpm dev:agent prints 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:migrate

The 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

.env
# 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:agent

It 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

ProviderChoose it for
E2BExecute scripts in an E2B runner
Alibaba Cloud SandboxUse an Alibaba Cloud runner image
Novita SandboxUse an existing Novita sandbox
SearXNGSearch through a self-hosted instance
Crawl4AIExtract 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.

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-skills

The 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.js

Give 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-skills

Both are idempotent. A deploy that changed no migration and no skill writes nothing.

Verify

  1. pnpm db:migrate reports 0016_agent_starter applied, in the dialect you deploy.
  2. /admin/config/sandbox shows the sandbox as configured, with the key held in the admin config table and not shown on the page.
  3. /admin/config/search reports a successful test connection for each provider you enabled.
  4. curl -i http://127.0.0.1:5173/api/agent/threads without a session answers 401. Signed in, it returns only your own threads.
  5. The agent service answers GET /healthz with status: "ok", and GET /readyz answers 200 with database, schema, objectStorage and providers all ready once the scenes and the sandbox are configured.
  6. /app/agent runs 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:

ReasonFix
plugin_disabledSwitch agent-starter on in Settings → Plugins.
database_not_transactionalThe database is D1. Use Postgres, or SQLite on Node.
service_not_configuredSet AGENT_SERVICE_URL, or on Cloudflare add the AGENT_SERVICE container binding.
signing_secret_missingSet 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/.

Reference

Next steps