Agentuity Docs

Run the development server with hot reload, local mode, and the interactive Workbench.

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

Option	Default	Description
`--port`	3500	TCP port for the dev server
`--local`	false	Use local services instead of cloud
`--public`	true	Enable public URL tunneling
`--no-public`	-	Disable public URL tunneling
`--interactive`	true	Enable interactive keyboard shortcuts
`--watch <path>`	-	Additional paths to watch for changes (repeatable)

# 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

Watching External Packages

Use --watch when developing with local packages outside your project. Changes in watched paths trigger rebuilds just like changes in your source directory.

Keyboard Shortcuts

Press keys during development to control the server:

Key	Action
`h`	Show help
`c`	Clear console
`r`	Restart server
`o`	Show routes
`a`	Show agents
`q`	Quit

Local Mode

Use --local to develop offline without cloud services:

agentuity dev --local

When to Use Local Mode

Local mode disables cloud services (KV, Vector, Object Storage). Use when developing without internet or testing with mock data.

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.

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

Public URL Tunneling

The --public flag creates a secure tunnel through Agentuity's edge network. Your local server gets 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.

Features:

Test agents with custom inputs or generated data (based on the agent's schema)
View request/response data
Inspect agent metadata
Explore available routes

Setup Required

Enable the Workbench in your app.ts:

import { createApp, createWorkbench } from '@agentuity/runtime';
 
const app = createApp();
const workbench = createWorkbench({ route: '/workbench' });
 
export default app;

Building Your Project

Bundle your project for deployment:

agentuity build

What happens during build:

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

Build Options

Option	Default	Description
`--dev`	false	Enable development mode
`--outdir`	`.agentuity`	Output directory
`--skip-type-check`	false	Skip TypeScript type checking

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

Type Check Failures

Build fails if TypeScript errors are detected. Fix type errors or use --skip-type-check to override (not recommended for deployments).

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.

Development vs Production

Understanding the differences between local development and deployed production:

Aspect	Local (`agentuity dev`)	Production (`agentuity deploy`)
Storage	Cloud services (or local with `--local`)	Cloud services always
AI Gateway	Available (or BYO keys with `--local`)	Available always
URL	`localhost:3500` + optional public tunnel	`*.agentuity.cloud` or custom domain
Hot Reload	Yes	No (redeploy required)
Debugging	Local logs, Workbench	SSH access, cloud logs
Environment	`.env`	`.env.production` (synced to cloud)

Next Steps

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

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Local Development