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

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:

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';
 
export default await createApp({
  services: {
    useLocal: true,
    keyvalue: new MyCustomKV(), // Your implementation
  },
});

See Custom Storage for implementation details.

Public URLs

Public URLs are enabled by default to share your local dev server or receive webhooks:

# Public URL enabled by default
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, 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

  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:

Environment Files

The dev server loads environment variables from multiple .env files. Put shared config in .env and dev-specific overrides in .env.development. Values in .env.development override those in .env. 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