> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Local development commands
description: Reference for running an AGNT5 worker locally with hot-reload, and for the container-based development environment.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 dev`** runs your worker locally and connects it to AGNT5, with hot-reload on file changes. It has two independent modes: a foreground/background **worker process** (`dev`, `dev stop`, `dev logs`, `dev status`) and a **container-based dev server** (`dev up`, `dev down`) that runs the full local stack.


**Commands**: `agnt5 dev [options]`, `agnt5 dev stop`, `agnt5 dev logs`, `agnt5 dev status`, `agnt5 dev up`, `agnt5 dev down`
**Key flags**: `--detached`/`-d`, `--no-watch`, `--verbose`/`-v` (worker process); `--runtime`, `--port`, `--no-cache`, `--no-mcp` (`dev up`)
**Side effects**: starts a local worker process or container connected to AGNT5; `dev up` starts an MCP server for editor/agent integration unless `--no-mcp` is set


## Command summary

| Command | Purpose |
| --- | --- |
| `dev` | Run the worker in the foreground (or `-d` for background) with hot-reload. |
| `dev stop` | Stop the background worker for the current project. |
| `dev logs` | Show logs from a detached worker. |
| `dev status` | Show the background worker's status. |
| `dev up` | Start the container-based development environment. |
| `dev down` | Stop the development environment. |

## `agnt5 dev`

```bash
agnt5 dev [options]
```

Starts your worker locally, connected to AGNT5. Runs in the foreground by default with file-watching and hot-reload; use `--detached` to run it in the background instead.

| Flag | Description |
| --- | --- |
| `--detached`, `-d` | Run in the background instead of the foreground. |
| `--no-watch` | Disable file watching and hot-reload. |
| `--verbose`, `-v` | Verbose worker logging. Sets `RUST_LOG=info,agnt5=debug,sdk_core=debug` and `AGNT5_DEBUG=1` if not already set. |

```bash
agnt5 dev
agnt5 dev --detached
agnt5 dev --no-watch --verbose
```

## `agnt5 dev stop`

```bash
agnt5 dev stop
```

Stops the background worker for the current project. No flags.

## `agnt5 dev logs`

```bash
agnt5 dev logs [options]
```

Shows logs from a detached (`--detached`) worker.

| Flag | Description |
| --- | --- |
| `--follow`, `-f` | Follow log output. |
| `--tail <n>`, `-n` | Number of lines to show from the end. Default: `50`. |

```bash
agnt5 dev logs --follow
agnt5 dev logs --tail 200
```

## `agnt5 dev status`

```bash
agnt5 dev status
```

Shows the background worker's status for the current project. No flags.

## `agnt5 dev up`

```bash
agnt5 dev up [options]
```

Starts the container-based development environment — a single container running the full local AGNT5 stack, with runtime auto-detected from the project (Python, Node, or Go).

| Flag | Description |
| --- | --- |
| `--runtime <lang>`, `-r` | Override runtime detection: `python`, `node`, or `go`. |
| `--service <name>`, `-s` | Override the service name. Default: current directory name. |
| `--no-cache` | Skip cache volume mounts. Slower, but cleaner for troubleshooting. |
| `--no-mcp` | Don't start the MCP server used for editor/agent integration. |
| `--port <n>`, `-p` | Base port for the dev server; uses `port`, `port+1`, `port+2`. Default: `34180`. |

```bash
agnt5 dev up
agnt5 dev up --runtime python --port 34280
agnt5 dev up --no-cache --no-mcp
```

## `agnt5 dev down`

```bash
agnt5 dev down [options]
```

Stops the development environment for the current project.

| Flag | Description |
| --- | --- |
| `--all` | Stop all running dev servers, not just the current project's. |

```bash
agnt5 dev down
agnt5 dev down --all
```

## Next steps

- [Run commands](/docs/cli/run.md): execute a function, workflow, tool, or agent against your running worker.
- [Inspect & logs](/docs/cli/inspect.md): trace and debug runs while developing locally.
- [Project & workspace commands](/docs/cli/project.md): scaffold a project before running `agnt5 dev`.
- [Automation & agents](/docs/cli/automation.md): connect an editor or agent to the MCP server `dev up` starts.