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

# Local development

> Run your app on your machine with marina dev and see changes instantly.

Run your app locally while you build it:

```bash theme={null}
marina dev               # http://localhost:5990
marina dev --port 4000
marina dev --schedules   # also run scheduled jobs on their timers
```

Open the printed URL, edit your code, and save. The app reloads in place.
Every service your app uses in production also works locally. No Docker, no
setup.

## How it works

`marina dev` is driven entirely by the project's `marina.json`, the same
manifest a deploy uses. It requires two things: a signed-in CLI
(`marina setup`) and a manifest with an `entrypoint`. A static project with
no entrypoint has no handler to run locally; deploy it instead.

| Manifest field | What marina dev does with it |
| - | - |
| `entrypoint` | Bundled and served at the local URL, reloading on every save. |
| `runtime` | Declared services are provided; undeclared services fail with the declaration to add, exactly as deployed. |
| `jobs` | Job handlers become enqueueable; schedules run with `--schedules`. |
| `connections` | Declared connections are callable through Marina, using your access. |

Because the manifest drives both environments, code that works under
`marina dev` behaves the same when deployed.

## Where @marina/runtime comes from

You do not install it. The `@marina/runtime` import is supplied by Marina at
build time: deployments and `marina dev` both resolve it to the same runtime
files, so there is no package version to manage and nothing to add to
`package.json`.

## What works locally

| Your app uses | What happens |
| - | - |
| [Database](/guides/database) | A real Postgres runs on your machine. Migrations in `marina/migrations/` apply automatically on first start, and data persists between runs. |
| [Storage](/guides/storage) | Files are stored under `.marina/dev/storage` in the project. |
| [Jobs](/guides/jobs) | Enqueued jobs run immediately, in-process. Scheduled jobs run only with `--schedules`. |
| [Connections](/connections/overview) | Calls go through Marina using your account, so you develop against live data. Credentials stay in Marina and are never downloaded to your machine. |
| [AI](/guides/ai) | `marina.ai` works, using your workspace's models. |
| [Temporary links](/guides/temporary-links) | `marina.grants.create` returns links to the local URL. Link requests reach your app with the same headers as in production, but the local server does not enforce a link's path, methods, or expiry. |
| [App keys](/guides/app-keys) | Not checked locally. Every request without a link arrives as you, with `x-platform-principal: user`. Test scope checks against a deployed app. |

Pages carry a small "local dev" badge identifying the local instance, and
your app sees you as the signed-in user.

## Using live data

Connection calls run as you, so access depends on your own permissions:

* **Admins** can use every connection.
* **Other members** need dev access on a connection, granted by an admin
  under Settings → Connections → Dev access. Without it, calls fail with
  `dev access not granted`.
* Connections configured so that **each person connects their own account**
  require you to connect yours first, under Settings → Your connections. No
  dev-access grant is needed there.

## Resetting local state

Local database, storage, and job state are disposable. Delete the
`.marina/dev` directory in the project to reset all of it. The next
`marina dev` reapplies migrations to a fresh database.

## Troubleshooting

| Symptom | Resolution |
| - | - |
| An error says you are not signed in | Sign in with `marina setup`. Local development uses your Marina account, even for apps that only use local services. |
| An error says the project needs an entrypoint | `marina dev` runs your handler; add an `entrypoint` to `marina.json`. Static-only projects have nothing to run locally. |
| A connection call fails with `dev access not granted` | Ask an admin for dev access on that connection, or connect your own account if it is a per-person connection. |
| A job enqueue fails with `job "…" is not defined in marina.json` | Declare the job in `marina.json` with a `handler` naming the function in your app's `jobs` map: `"jobs": { "count_visits": { "handler": "count_visits", "schedule": "*/5 * * * *" } }` |
| Scheduled jobs never fire | Schedules are off by default. Pass `--schedules`. |
| A `marina.json` change has no effect | Manifest changes require a restart. Code changes reload automatically. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.