amodal dev

Start a local runtime server for development. The server watches your repo config files and hot-reloads on every change.

amodal dev

Options

Flag	Default	Description
`--port`	`3847`	Runtime server port
`--host`	`0.0.0.0`	Server host
`--resume`		Resume a previous session by ID or `latest`
`--no-studio`	`false`	Do not spawn Studio subprocess
`--no-admin`	`false`	Do not spawn admin agent subprocess
`-v`		Increase log verbosity (`-v` for debug, `-vv` for trace)
`-q` / `--quiet`		Only show errors

If the runtime port (default 3847), Studio port (3848), or admin agent port (3849) is already in use, amodal dev will fail with an error. Stop the existing process or use --port to select a different runtime port.

Log Levels

The default log level is info — startup messages, connection status, and warnings. Use -v or -vv to see more, or -q to see less.

Flag	Level	What you see
`-q`	error	Errors and fatal only
(default)	info	Startup, connections, warnings
`-v`	debug	Session init, MCP, store ops, config reload
`-vv`	trace	Tool execution, upstream library output

You can also set the LOG_LEVEL environment variable (trace, debug, info, warn, error, fatal, none). The env var takes precedence over CLI flags.

# Quiet mode
amodal dev -q
 
# Debug output
amodal dev -v
 
# Full trace (including upstream library noise)
amodal dev -vv
 
# Via environment variable
LOG_LEVEL=debug amodal dev

What It Does

Loads your repo configuration from the project root
Starts an Express server with SSE streaming
Watches all config files with 300ms debounce
Manages sessions with TTL-based cleanup

Endpoints

The dev server exposes:

Method	Path	Description
`POST`	`/chat/stream`	Send a message, receive SSE stream
`POST`	`/chat/sync`	Send a message, get a complete response
`POST`	`/task`	Start a background task
`GET`	`/task/:id`	Get task status
`GET`	`/task/:id/stream`	Stream task output
`GET`	`/sessions/history`	List sessions
`GET`	`/sessions/history/:id`	Get session history
`GET`	`/inspect/context`	View compiled context with token counts
`GET`	`/api/events`	Runtime event bus (SSE)
`GET`	`/health`	Health check

SSE Events

The chat endpoint returns a Server-Sent Events stream with these event types:

Event	Description
`init`	Session created or resumed
`text_delta`	Incremental text output from the LLM
`tool_call_start`	Tool execution beginning
`tool_call_result`	Tool execution complete
`subagent_event`	Task agent activity
`skill_activated`	Skill activation
`widget`	Widget rendered inline
`confirmation_required`	Write operation needs approval
`error`	Error occurred
`done`	Response complete

See Runtime Server for the full event reference.

Hot Reload

Edit any config file and the runtime picks up changes immediately:

Connection specs, skills, knowledge, tools, automations
Config changes (provider, model, etc.)
No server restart needed