# primitives dev

> Run the engine locally: REST API and MCP on localhost:7777, with idle and signed-URL options.

Source: https://useprimitives.com/docs/cli/dev

`primitives dev` runs the engine as a local server: the [REST API](/docs/api) and [MCP](/docs/mcp) on one port, for you on your machine.

```bash
primitives dev
```

```text
primitives dev — data in .primitives, REST + MCP on http://127.0.0.1:7777
MCP: http://127.0.0.1:7777/mcp/<group>  (no token needed locally)
```

It runs in the foreground until Ctrl-C or `SIGTERM`. On shutdown it stops accepting connections, lets open requests finish for up to 20 seconds, then closes every group cleanly.

## Options

| Option | Environment | Default | Description |
| --- | --- | --- | --- |
| `--port <PORT>` | `PRIMITIVES_PORT` | `7777` | Port to listen on |
| `--signed-url-base <URL>` | `PRIMITIVES_SIGNED_URL_BASE` | `http://127.0.0.1:<port>` | Base URL of [signed storage URLs](/docs/api/signed-urls). Set it when uploads or downloads go through a tunnel or proxy |
| `--idle-timeout <DURATION>` | `PRIMITIVES_IDLE_TIMEOUT` | `10m` | Close the files of groups unused for this long. `0` never sleeps a group by age |
| `--idle-sweep-interval <DURATION>` | `PRIMITIVES_IDLE_SWEEP_INTERVAL` | `60s` | How often idle groups are swept. `0` turns sweeping off |
| `--max-loaded-groups <N>` | `PRIMITIVES_MAX_LOADED_GROUPS` | `0` | Most groups kept open. Beyond it, the least recently used are slept at each sweep. `0` means no cap |
| `--data <DIR>` | `PRIMITIVES_DATA` | `.primitives` | Data directory. See [global options](/docs/cli#global-options) |

Durations take `ms`, `s`, `m`, `h` or `d`, such as `30s` or `5m`; a bare number means seconds. A slept group reopens on its next call, so idle settings affect memory use, never behaviour.

## Local only

`primitives dev` binds `127.0.0.1` and has no credentials: it serves you, on your machine.

- There is no `--host` option. It can't listen on other interfaces.
- There are no API keys. Requests need no `Authorization` header, and MCP needs no token.
- Requests addressed to another host and cross-site requests from browser pages are refused.
- The [audit log](/docs/concepts/audit) is a cloud feature and isn't served locally.

To reach groups from other machines, with API keys and an audit trail, use [Primitives Cloud](/docs/quickstart#cloud).

## Examples

Run on another port with its own data:

```bash
primitives --data ~/agents/.primitives dev --port 8080
```

Keep at most 50 groups open, sweeping every 30 seconds:

```bash
primitives dev --max-loaded-groups 50 --idle-sweep-interval 30s
```

Use real embeddings for memory recall:

```bash
export PRIMITIVES_EMBEDDINGS_URL="https://api.openai.com/v1"
export PRIMITIVES_EMBEDDINGS_KEY="sk-…"
primitives dev
```

Check it's up:

```bash
curl http://localhost:7777/health
```

```json
{ "ok": true, "version": "0.2.0" }
```

Then point an [SDK](/docs/sdk) at it (both default to `http://localhost:7777`), or [connect an MCP client](/docs/mcp/setup) to `http://localhost:7777/mcp/<group>`.