Running Local Development

agentuity dev runs your framework's dev script as a child process and patches Agentuity values into that process's environment. The framework keeps owning the dev server, hot reload, and the route table. Agentuity's job is to wire AGENTUITY_SDK_KEY and the AI Gateway base URLs in front of your provider SDKs.

agentuity dev

These examples show agentuity ... for readability. If the CLI is project-local, run the same command through your package-manager exec wrapper, for example npx agentuity ..., bunx agentuity ..., pnpm exec agentuity ..., or yarn exec agentuity .... See Local versus global CLI for install and undo commands.

What it runs

The CLI reads package.json, picks the package manager from the lockfile in the project root, and runs the chosen script:

The default script name is dev. Use --script when your dev script does something other than starting your framework, or when you want a non-standard script:

{
  "scripts": {
    "dev": "agentuity dev --script dev:start",
    "dev:start": "next dev --port 3000"
  }
}

This is the recommended pattern for existing apps. Keep your real dev command in dev:start and let dev wrap it through Agentuity. agentuity dev and npm run dev then do the same thing.

If the named script is missing, the CLI prints the available scripts and exits.

Local Environment Loading

The CLI looks up AGENTUITY_SDK_KEY in your .env files using the active profile. The default profile is production. The local profile (local) loads a different file order so dev overrides do not bleed into other profiles.

Switch profiles with --profile <name> or the AGENTUITY_PROFILE env var. The framework dev server reads its own variables. The CLI does not parse .env for your app, only for the SDK key it needs to wire the gateway.

If no project SDK key is found, the CLI falls back to your CLI auth key for gateway routing and reminds you to run agentuity project import so the project gets its own key.

AI Gateway in Local Dev

agentuity dev automatically injects env vars for the SDKs that read provider API key and base URL values from process env. Other AI SDK providers need an explicit provider factory or a provider-owned key.

For OpenAI, Anthropic, and Groq, the automatic patch only runs when the provider API key is missing or already equals AGENTUITY_SDK_KEY. If you set a real provider key in .env, the CLI leaves it alone and your call goes straight to that provider.

For provider SDKs outside the automatic patch list, configure the provider factory yourself. Use provider-owned keys unless your project has a confirmed Agentuity gateway base URL for that provider:

import { createGoogleGenerativeAI } from '@ai-sdk/google';
 
const apiKey = process.env.GOOGLE_GENERATIVE_AI_API_KEY;
 
if (!apiKey) {
  throw new Error('Set GOOGLE_GENERATIVE_AI_API_KEY.');
}
 
export const google = createGoogleGenerativeAI({
  apiKey,
});

Port

agentuity dev sets PORT for the child process. The default is 3000. Pass --port when your framework should listen elsewhere:

agentuity dev --port 4321

Some frameworks ignore PORT and require a CLI flag in the dev script itself. Our SvelteKit, React Router, and TanStack Start examples use dev:start wrappers with --port 3000 for that reason. Next.js can read PORT directly, though next dev --port 3000 is also valid when you want the port pinned in the script.

Public Dev URL

By default, agentuity dev asks whether to expose the dev server through a public Gravity URL. The answer is stored in agentuity.json:

{
  "devmode": {
    "public": false
  }
}

Force a public URL for the current run:

agentuity dev --public

When the tunnel starts, the CLI prints both URLs and passes these values to the child process:

Vite-based apps should install @agentuity/vite and include the plugin in vite.config.ts. The plugin reads AGENTUITY_DEVMODE_HOSTNAME, adds the public hostname to Vite's allowed hosts, and configures HMR over wss.

import { agentuity } from '@agentuity/vite';
import { defineConfig } from 'vite';
 
export default defineConfig({
  plugins: [agentuity()],
});

Validate Project Shape

When you want to confirm a directory looks right without registering it or writing files, run import in validate-only mode:

agentuity project import --validate-only

The check accepts a package.json with at least one of name, dependencies, or devDependencies, or an agentuity/ subdirectory containing a package.json. Nothing is written and nothing is created in the cloud.

Local vs Deployed

Next Steps

• Deploy Framework Apps: register the project, package the bundle, ship it.
• Environment Variables: which values go in .env, which go in cloud project vars, what becomes a secret.
• Dev Options: every CLI flag for agentuity dev.
• Framework Scripts: more on --script and the dev:start wrapper pattern.