Agentuity Documentation

Your framework owns routing, startup, and the dev server. Agentuity configuration spans package.json scripts, agentuity.json for cloud metadata, environment variables, and the service clients you import in routes and scripts.

package.json

The framework's create command writes dev, build, and start. The Agentuity scaffold adds deploy:

jsonpackage.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "deploy": "agentuity deploy"
  }
}

npm run deploy runs the local devDependency CLI, so it works without a global install.

For local dev, wrap the framework's dev server through the CLI to wire AGENTUITY_SDK_KEY and AI Gateway base URLs:

npx agentuity dev
npx agentuity dev --port 8080
npx agentuity dev --script dev:web

agentuity dev reads package.json, picks the runner from the lockfile, and runs the named script. Default script name is dev.

agentuity.json

agentuity.json stores cloud metadata and deploy settings. The file is created when the project is registered:

jsonagentuity.json

{
  "$schema": "https://agentuity.dev/schema/cli/v1/agentuity.json",
  "projectId": "proj_...",
  "orgId": "org_...",
  "region": "usc",
  "deployment": {
    "resources": {
      "memory": "500Mi",
      "cpu": "500m",
      "disk": "500Mi"
    },
    "domains": []
  }
}

agentuity project create writes the file during interactive scaffolding. agentuity project import writes it later for an existing local app. The default .gitignore entry excludes it; the file is per-machine and can be regenerated by re-importing the project.

Keep app routing in the framework

agentuity.json covers project metadata and deploy resources. Pages, API routes, middleware, and server handlers stay in the framework's own files.

Deployment Resources

deployment.resources sizes the running app. build.resources sizes the cloud build sandbox separately. Override either when defaults aren't enough:

jsonagentuity.json

{
  "$schema": "https://agentuity.dev/schema/cli/v1/agentuity.json",
  "projectId": "proj_...",
  "orgId": "org_...",
  "region": "usc",
  "deployment": {
    "resources": {
      "memory": "500Mi",
      "cpu": "500m",
      "disk": "500Mi"
    },
    "domains": ["app.example.com"]
  },
  "build": {
    "timeout": "30m",
    "resources": {
      "memory": "4Gi",
      "cpu": "2",
      "disk": "4Gi"
    }
  }
}

Increase build.resources when dependency installation or framework compilation is hitting limits. Increase deployment.resources when the running app is memory- or CPU-bound. See Building Deployment Bundles for build options and Deploying with the CLI for the resource schema.

Environment Variables

The CLI manages a small, named set of Agentuity values and leaves everything else to your framework's loader.

Agentuity Keys

Variable	Read by	Purpose
`AGENTUITY_SDK_KEY`	service clients, AI Gateway, `agentuity dev`	The project's SDK key, written to `.env` by `agentuity project create` or `agentuity project import`
`AGENTUITY_CLI_KEY`	service clients, as a fallback when `AGENTUITY_SDK_KEY` is missing	Useful in scripts that share an auth key
`AGENTUITY_REGION`	service clients	Targets a non-default region; default is `usc`
`AGENTUITY_PROFILE`	the CLI	Switches the local config and `.env` profile (`local`, `production`, etc.)

AGENTUITY_SDK_KEY is the only Agentuity value the local CLI loads from .env files for the dev process.

Provider Keys

agentuity dev patches gateway base URLs into the dev process for OpenAI, Anthropic, and Groq SDKs:

Variable	Behavior in `agentuity dev`
`OPENAI_API_KEY`	If unset (or equals `AGENTUITY_SDK_KEY`), routed through the gateway with `OPENAI_BASE_URL` set
`ANTHROPIC_API_KEY`	Same routing through `ANTHROPIC_BASE_URL`
`GROQ_API_KEY`	Same routing through `GROQ_BASE_URL`

Set a real provider key in .env to bypass the gateway and call the provider directly.

bash.env

AGENTUITY_SDK_KEY=sdk_...
# Optional: bypass the gateway for OpenAI calls
# OPENAI_API_KEY=sk-...

See Local Development for the full env loading order and AI Gateway for the provider list.

Public Variables

The CLI treats variables prefixed with AGENTUITY_PUBLIC_, VITE_, or PUBLIC_ as public when syncing to the cloud. Public values ship to the browser bundle.

Never put secrets in public variables

AGENTUITY_PUBLIC_*, VITE_*, and PUBLIC_* values are visible in the client bundle. Keep API keys, tokens, and signed URLs out of these prefixes.

Service Clients

Add Agentuity services to the route, server function, or script that needs them. Standalone clients read AGENTUITY_SDK_KEY automatically:

npm install @agentuity/keyvalue

import { KeyValueClient } from '@agentuity/keyvalue';
 
const kv = new KeyValueClient();
 
await kv.set('settings', 'theme', { value: 'dark' });

The same pattern works for queues, vector storage, email, schedules, tasks, sandbox, and the rest. See Using Standalone Packages for the package list and constructor options.

Deploy Lifecycle Scripts

Package manager lifecycle hooks fire when you call the package script:

jsonpackage.json

{
  "scripts": {
    "predeploy": "npm run typecheck",
    "deploy": "agentuity deploy",
    "postdeploy": "echo 'Deploy complete'"
  }
}

npm run deploy runs predeploy, the deploy script, and then postdeploy. Calling agentuity deploy directly skips both hooks.

Next Steps

Project Structure: see exactly what the scaffold adds
Frameworks: per-framework setup, route patterns, and deploy notes
Using Standalone Packages: every Agentuity service client and constructor option
Environment Variables: local files, cloud project values, and secrets
Deploying with the CLI: every deploy flag and resource option