Local Development

Run your Agentuity project locally with automatic hot reload, type checking, and the interactive Workbench UI.

Starting the Dev Server

agentuity dev
# or
bun run dev

The server starts on port 3500 by default with:

• Hot reload on file changes
• TypeScript type checking
• Public URL tunneling (optional, for webhooks and sharing)
• Interactive keyboard shortcuts

Dev Server Options

# Custom port
agentuity dev --port 8080
 
# Local mode (offline development)
agentuity dev --local
 
# Disable public URL
agentuity dev --no-public
 
# Non-interactive mode (useful for CI/CD)
agentuity dev --no-interactive
 
# Watch additional directories (e.g., local packages)
agentuity dev --watch ../my-shared-lib/dist --watch ../other-package/src

Keyboard Shortcuts

Press keys during development to control the server:

Local Mode

Use --local to develop offline without cloud services:

agentuity dev --local

What happens in local mode:

• No connection to Agentuity cloud
• Storage APIs disabled unless you provide custom implementations
• Public URL tunneling disabled
• Requires your own API keys for AI providers (in .env), since the AI Gateway is not available

Bring Your Own Storage:

// app.ts
import { createApp } from '@agentuity/runtime';
import { MyCustomKV } from './storage';
 
const app = createApp({
  services: {
    useLocal: true,
    keyvalue: new MyCustomKV(), // Your implementation
  },
});

See Custom Storage for implementation details.

Profile-Specific Environment Variables

Load different environment variables based on a profile name:

# Load .env.staging
agentuity dev --profile staging
 
# Load .env.testing
agentuity dev --profile testing

Profile-specific files are loaded in addition to the base .env file. Variables in the profile file override those in .env.

Example setup:

# .env (base, always loaded)
DATABASE_URL=postgres://localhost:5432/myapp
LOG_LEVEL=info
 
# .env.staging (loaded with --profile staging)
DATABASE_URL=postgres://staging.example.com:5432/myapp
API_BASE_URL=https://staging-api.example.com
 
# .env.testing (loaded with --profile testing)
DATABASE_URL=postgres://localhost:5432/myapp_test
MOCK_EXTERNAL_APIS=true

Public URLs

Enable public URLs to share your local dev server or receive webhooks:

# Public URL enabled by default
agentuity dev
 
# Or explicitly
agentuity dev --public

The --public flag creates a secure tunnel through Agentuity's edge network, giving your local server a public HTTPS URL for testing webhooks, sharing with teammates, or external integrations.

Example output:

⨺ Agentuity DevMode
  Local:   http://127.0.0.1:3500
  Public:  https://abc123.devmode.agentuity.com

  Press h for keyboard shortcuts

Example use cases:

• Testing Slack, Discord, or Twilio webhooks
• Sharing with team members
• Testing from mobile devices
• OAuth callback URLs

Workbench UI

Access the interactive Workbench at http://localhost:3500/workbench to test agents visually. It displays agent schemas, handles input validation, and shows execution results with timing metrics.

See Testing with Workbench for setup and configuration.

Building Your Project

Bundle your project for deployment:

agentuity build

What happens during build:

1. TypeScript compilation
2. Bundle agents, routes, and frontend
3. Generate registry and types
4. Type check with tsc
5. Create .agentuity/ output directory

Build Options

# Skip type checking (faster builds)
agentuity build --skip-type-check
 
# Custom output directory
agentuity build --outdir ./dist

Hot Reload Behavior

The dev server watches for file changes and automatically:

• Rebuilds on source file changes (.ts, .tsx, .js, .jsx)
• Runs TypeScript type checking
• Restarts the server
• Preserves background tasks

Ignored files:

• node_modules/
• .agentuity/ (build output)
• Generated files (*.generated.ts)
• Temporary files

Cooldown period: 500ms after build completes to prevent restart loops.

Dev Server Architecture

The dev server uses Vite for frontend hot module replacement (HMR) and Bun for server-side code. All requests go through a single port (3500), so you don't need to manage multiple servers or ports during development.

• Frontend changes (React, CSS) reload instantly via Vite HMR
• Server changes (agents, routes) trigger a fast Bun rebuild
• WebSocket connections work seamlessly

Development vs Production

Understanding the differences between local development and deployed production:

Next Steps

• Deploying to the Cloud: Deploy to Agentuity Cloud
• Creating Agents: Create your first agent
• HTTP Routes: Add HTTP endpoints