# Quick start

Run Ceryx on your machine and route your first hostname in a few seconds.

In this guide you run Ceryx and a small sample service on your machine, then route `echo.localhost` to the service. All you need is Docker with Compose.

## 1. Run Ceryx

```bash
docker compose -f 'https://github.com/withlogicco/ceryx.git#v1.0.0:docs/compose.example.yml' up -d
```

This starts two containers in a Compose project named `ceryx-example-echo`: Ceryx, and `echo`, a service that answers every request with the same message.

> [!TIP] Ports 80, 443 or 8080 already in use?
> Pick other ports on your machine with `CERYX_EXTERNAL_HTTP_PORT`, `CERYX_EXTERNAL_HTTPS_PORT` and `CERYX_EXTERNAL_API_PORT`.
> 
> For example, `CERYX_EXTERNAL_HTTP_PORT=8000` serves HTTP on port 8000, so you'd visit your the echo service from step 3 below at `http://echo.localhost:8000`.

## 2. Add a route

The sample setup makes the API available on your machine at `localhost:8080`. Route `echo.localhost` to the `echo` service:

```bash
curl -X POST localhost:8080/api/routes \
  -H 'Content-Type: application/json' \
  -d '{"source": "echo.localhost", "target": "http://echo:5678"}'
```

Ceryx answers with the new route and its default [settings](/docs/route-settings):

```json
{
  "source": "echo.localhost",
  "target": "http://echo:5678",
  "settings": {
    "enforce_https": false,
    "mode": "proxy",
    "certificate_path": null,
    "key_path": null,
    "mtls_require_client_certificate": false,
    "mtls_trusted_ca": null,
    "mtls_verify_depth": null
  }
}
```

## 3. Send a request

```bash
curl http://echo.localhost
```

```text
Hello from behind Ceryx
```

Hostnames ending in `.localhost` point to your own machine, so this works without setting up DNS. You can open [http://echo.localhost](http://echo.localhost) in your browser too.

## 4. Clean up

Stop the containers and remove their data:

```bash
docker compose -p ceryx-example-echo down -v
```

## Next steps

- [Deploy to production](/docs/deploy) to serve real domains over HTTPS.
- [Local development](/docs/use-cases/local-development) to keep Ceryx running for your own projects.
- [How routing works](/docs/concepts/routing) to see what Ceryx does with each request.