> ## Documentation Index
> Fetch the complete documentation index at: https://docs.specific.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> Run your complete system locally with a single command.

`specific dev` starts everything your project needs locally with a single command: databases, caches, object storage, real-time sync, durable workflows, and application services.

```bash theme={null}
specific dev
```

Specific reads `specific.hcl` and:

1. Installs and starts all required resources (Postgres, Redis, storage, sync, Temporal).
2. Starts your application services, using their `dev` commands where defined.
3. Launches the [local dashboard](/concepts/dashboard#the-local-dashboard).

All connection details (database URLs, S3 credentials, ports) are injected into your services as environment variables. No `.env` files needed. The terminal output includes the URL of every service and the local dashboard.

## Ports

Every service and resource gets its own local port, assigned automatically at startup. The local dashboard usually lands at `http://localhost:3000` with services on the ports next to it, and the exact URLs are printed when `specific dev` starts. Running several instances at once is fine; each gets its own set of ports.

Reference ports with `port` (or `endpoint.<name>.port`) in `specific.hcl` and read them from the environment in your code.

## Config file watching

While `specific dev` is running, changes to `specific.hcl` are detected automatically. As your coding agent updates the configuration, the environment reloads: new services start, removed services stop, and resource changes take effect without a manual restart.

## Service logs

Each service's stdout and stderr are written to a per-service log file:

```
.specific/keys/<key>/logs/<service>.log
```

Without `--key`, the path is `.specific/keys/default/logs/<service>.log`. Each line is prefixed with an ISO-8601 timestamp and the stream it came from:

```
[2026-05-06T14:23:11.482Z] [stdout] Listening on port 3001
[2026-05-06T14:23:11.500Z] [stderr] warning: deprecated API
```

This makes logs easy for you or your coding agent to read or grep when debugging, instead of watching the live `specific dev` output:

```bash theme={null}
tail -f .specific/keys/default/logs/api.log
grep -i error .specific/keys/default/logs/api.log
```

Each file is capped at 1 MB. When a service produces more output, the file is truncated to the most recent \~512 KB on a line boundary, so the path is stable and always contains the latest logs.

## One-off commands

Use `specific exec` to run commands with a service's environment: migrations, seeds, scripts. If `specific dev` is running, it reuses the running resources; otherwise it starts what's needed temporarily:

```bash theme={null}
specific exec api -- npm run db:migrate
```

Use `specific psql` for an interactive database session, and `specific clean` to wipe local data for a fresh start. See the [CLI reference](/reference/cli).

## Multiple instances

Run isolated dev environments side by side with `--key`. Each instance gets its own data and its own ports:

```bash theme={null}
specific dev --key feature-auth
```

Each instance stores its state under `.specific/keys/<key>/`, so databases and other data are fully isolated.

**Automatic git worktree detection:** when working in a git worktree, Specific uses the worktree name as the instance key automatically; no `--key` flag needed.

## Tunnel mode

Expose your local services to the internet with `--tunnel`. Each public service gets a publicly reachable URL, useful for sharing work, testing webhooks, or letting a remote agent reach your machine:

```bash theme={null}
specific dev --tunnel
```

Services are available at:

```
https://<subdomain>.tunnel.spcf.app
```