> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# Choose How to Run Amp

You can use Amp in three ways: connect to an Amp someone else runs, run it on your machine in one process, or run its
services separately in production. They all answer the same SQL and accept the same datasets, and the same CLIs and
SDKs work with all three, so you can start with one and move to another later.

|                      | Hosted Amp                                   | Solo mode                             | Distributed mode                                         |
| -------------------- | -------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
| **Who runs Amp**     | Its operator, like Edge & Node               | You, in one process                   | You, as separate services                                |
| **What you need**    | Its URLs and a token                         | PostgreSQL 16 or newer                | PostgreSQL, shared storage, and a way to deploy services |
| **What it's for**    | Querying data, and publishing datasets on it | Development, testing, and CI          | Production                                               |
| **What you control** | What your access allows                      | Everything, on one machine            | Everything, including how each service scales            |
| **Get started**      | [Connect to it](/get-started/choose-how-to-run-amp#connect-to-a-hosted-amp)    | [Quickstart](/get-started/quickstart) | [Distributed Mode](/running-amp/distributed-mode)        |

If you only want to explore and query datasets, you don't need any of them: the
[Amp app](https://app.ampdb.io) runs in your browser, on Edge & Node's hosted Amp.

## Connect to a hosted Amp

Someone else runs Amp's services, its database, and its storage, and keeps them up and up to date. You send queries,
and, if your access allows it, register and deploy your own datasets. Edge & Node runs one, which the Amp app uses, and
your organization may run its own, in distributed mode.

Choose a hosted Amp when you want Amp's data and queries without running infrastructure. The trade-off is control:
the operator decides which chains and providers are available, how much you can query, and which Amp release runs.

### What you need

The operator gives you:

* **The query URL**, where its query server answers SQL over [Arrow Flight](/querying/arrow-flight).
* **The Admin API URL**, if you can manage datasets. The [Admin API](/managing-amp/admin-api) is what `ampctl` and the
  SDKs' admin clients talk to.
* **A token**, which proves who you are with every request. Amp itself doesn't check tokens: the operator's own service
  in front of Amp does, and decides what each token allows.

What you can do depends on the access your token grants. Datasets live in namespaces, which group them by owner, like
`edgeandnode` or your organization's, and the operator gives you read access to some namespaces and write access to
others. You can query the datasets in namespaces you can read, and register, deploy, and remove datasets in namespaces
you can write.

### Point the CLIs at it

`ampsql` and `ampctl` read the hosted Amp's URLs and your token from environment variables:

```bash
export AMP_QUERY_URL=…    # the query URL, for ampsql
export AMP_ADMIN_URL=…    # the Admin API URL, for ampctl
export AMP_AUTH_TOKEN=…   # your token, for both
```

The [Quickstart](/get-started/quickstart)'s `ampctl` and `ampsql` commands then work against the hosted Amp, for the
datasets and namespaces your token allows. Use a namespace you can write to instead of `acme`. Registering providers is
usually up to the operator. The SDKs take the same token, and the TypeScript SDK the same URLs. The Python SDK needs a `grpc+tls://` query URL. See
[TypeScript](/sdks/typescript/authentication) and [Python](/sdks/python/authentication).

## Run Amp yourself

You run `ampd`, the Amp daemon, on your own machines. It runs Amp's three services:

* The **query server** answers SQL queries.
* The **controller** serves the Admin API and schedules work.
* **Workers** extract and transform data.

They share two stores: a **PostgreSQL** database for Amp's metadata, and **storage** for the data, as Parquet files.
[Architecture](/get-started/concepts/architecture) explains how they work together.

Run Amp yourself when you need your own chains, providers, or release of Amp, data that stays in your infrastructure,
or capacity that only you decide on. You then operate it: its database, storage, upgrades, and security.

`ampd` runs the services in one of two modes.

### Solo mode

`ampd solo` runs all three services in one process, with a single worker, on your machine. It needs no configuration:
it keeps its state in a `.amp` directory, and can start and stop PostgreSQL for you.

Choose solo mode for local development, testing, CI, and learning Amp. Don't use it in production:

* **No isolation**: extraction and queries compete for the same CPU and memory, and if any part fails, the whole
  process stops.
* **One worker**: extraction can't scale beyond one machine.
* **No high availability**: when the process stops, so does everything.

The [Quickstart](/get-started/quickstart) runs Amp in solo mode, and [Solo Mode](/running-amp/solo-mode) covers its
options.

### Distributed mode

In distributed mode, each service is its own process, which you deploy and scale independently:

```bash
ampd controller
ampd server
ampd worker --node-id worker-01
```

All of them share one PostgreSQL database and one storage location: an object store, like Amazon S3, an S3-compatible
store, Google Cloud Storage, or Azure Blob Storage. Each reads a configuration file, which you give it with `--config`
or the `AMP_CONFIG` environment variable.

Choose distributed mode for production:

* **Scale what you need**: add workers to extract more, and query servers to answer more queries.
* **Isolation**: extraction doesn't slow queries down, and a failing worker doesn't stop the other services.

A production deployment usually looks like this:

```text
clients ──▶ query server(s) ──┐
                              ├── PostgreSQL metadata
operators ──▶ controller ─────┤
                              └── shared object storage
                 ▲                        ▲
                 └──── worker(s) ─────────┘
```

:::warning
Amp doesn't authenticate requests or encrypt connections (TLS). Keep the controller and workers on a private network,
and put the query servers behind your own authentication, TLS, rate limiting, and load balancing.
:::

[Distributed Mode](/running-amp/distributed-mode) explains how to deploy it, and
[Configuration](/running-amp/configuration) how to configure it.

## Moving between them

* **Datasets move with their manifests.** A dataset is defined by its manifest, a JSON file. Register the same manifest
  on another Amp, and deploy it there, to extract the same data.
* **Clients only change URLs.** `ampctl`, `ampsql`, the SDKs, and your queries work the same everywhere. Change the URLs
  and token they use.
* **Data doesn't move by itself.** Each Amp extracts into its own storage. Going from solo to distributed mode, deploy
  your datasets again, or [restore](/managing-amp/table-revisions) their tables from existing files.