Local Development

Run your Agentuity project locally with automatic hot reload and type checking. If your project is connected to Agentuity Cloud, agentuity dev also enables a public URL by default outside CI for sharing or webhook testing.

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 when cloud-connected (disable with --no-public)
• Interactive keyboard shortcuts

Dev Server Options

# Custom port
agentuity dev --port 8080
 
# Disable public URL
agentuity dev --no-public
 
# Non-interactive mode (useful for CI/CD)
agentuity dev --no-interactive
 
# Local services mode
agentuity dev --local

Debugging with Inspector

Use the inspector flags to debug your agents with Chrome DevTools or VS Code:

# Enable inspector (attach debugger anytime)
agentuity dev --inspect
 
# Wait for debugger before starting the server
agentuity dev --inspect-wait
 
# Break on first line of executed code
agentuity dev --inspect-brk

Bun dynamically selects an available port and prints it to the console. Check the output for the debugger URL and port number.

After starting, open chrome://inspect in Chrome or use VS Code's debugger to attach.

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Agentuity",
  "port": 6499
}

Keyboard Shortcuts

Press keys during development to control the server:

Public URLs

If your project is connected to Agentuity Cloud, public URLs are enabled by default outside CI to share your local dev server or receive webhooks:

# Public URL enabled by default outside CI
agentuity dev
 
# Disable if not needed
agentuity dev --no-public

Why Public URLs?

Testing webhooks and external integrations during local development is painful. You either deploy constantly, configure port forwarding, or pay for third-party tunneling services. Each option adds friction to the development loop.

Agentuity's Gravity network handles this automatically. When you run agentuity dev on a connected project, your local server gets a public HTTPS URL instantly. No configuration, no separate tools, no accounts to manage. External services can reach your local agents as if they were already deployed.

This means:

• Instant HTTPS URLs: Automatic certificate generation
• Zero setup: Works out of the box, no firewall rules or port forwarding
• Secure tunneling: Encrypted connections through Agentuity's edge network
• Automatic reconnection: Handles network interruptions gracefully

Example output:

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

  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

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:

Environment Files

The dev server loads environment variables from multiple .env files. The CLI reads .env.development and .env, with .env winning if both define the same key. Bun also auto-loads .env.local for machine-specific values.

See Environment-Specific Files for the full loading order and examples.

Next Steps

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