Agentuity Documentation

agentuity dev runs your project's package script and passes the Agentuity environment it can resolve for the current project.

Starting the Dev Server

Run the default dev script:

agentuity dev

Pass a port through the PORT environment variable:

agentuity dev --port 8080

Some frameworks ignore PORT and need the flag in the framework command itself. For SvelteKit, React Router, and TanStack Start, wrap the real dev command behind dev:start:

jsonpackage.json

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

Next.js can read PORT directly, so this wrapper is optional there.

Run a different package script:

agentuity dev --script dev:web

The command reads package.json, detects the package manager, and runs that package manager's run command for the selected script. The framework still owns hot reload, routing, terminal output, and local server behavior.

Dev Options

Option	Default	Description
`--dir <path>`	current directory	Project directory
`--port <port>`	`3000`	Port to pass to the child process as `PORT`
`--script <script>`	`dev`	Package script to run
`--public`	`false` unless `agentuity.json` says otherwise	Expose the dev server through a public Gravity URL
`--project-id <id>`	inferred from project	Project ID, alternative to resolving from `--dir`

No --no-public flag

The CLI examples may mention agentuity dev --no-public, but the current parser rejects it. To disable a previously enabled public tunnel, set "devmode": { "public": false } in agentuity.json, or answer n when the CLI asks.

Environment Loading

agentuity dev starts with your current shell environment. If AGENTUITY_SDK_KEY is not already set, the CLI tries to load a project SDK key from local project configuration and .env files. If the project is not linked yet, it can fall back to your CLI auth key for AI Gateway routing and prints the import command to link the project.

agentuity project import --name my-app

When an Agentuity SDK key is available, the CLI can route supported provider SDKs through the Agentuity AI Gateway by setting provider API key and base URL environment variables in the child process.

Public Tunnel

When public mode is enabled, agentuity dev starts Gravity, prints the public URL, and injects:

Variable	Description
`AGENTUITY_DEVMODE_URL`	Full public URL
`AGENTUITY_DEVMODE_HOSTNAME`	Hostname without scheme

Vite-based apps should include @agentuity/vite so Vite accepts the public host and HMR works through the tunnel.

Framework Scripts

Use the same dev script you would use without Agentuity:

jsonpackage.json

{
  "scripts": {
    "dev": "next dev",
    "dev:web": "vite --host 0.0.0.0"
  }
}

Then choose the script at runtime:

agentuity dev --script dev:web

For generated Hono projects, agentuity dev is the local path to use today. If you are preparing a deployable bundle, see Build Configuration for the current build caveats.

Building Locally

Build a deployment bundle with:

agentuity build

The build command is separate from agentuity dev. It detects the framework, runs the build adapter, writes launch metadata, and creates the .agentuity output directory for deployment.

Environment Files

Keep local-only values in .env.local or your framework's standard local env file. Keep shared deploy values in .env when you want agentuity deploy to sync them to Agentuity Cloud.

See App Configuration for environment file conventions.

Next Steps

Build Configuration: Create and inspect the deployment bundle
Deployment: Deploy the registered project
App Configuration: Configure project and environment files