# Self-host Oriant

> Run the Oriant MCP gateway and dashboard on your own machine or server with Docker. Two commands, one Postgres, no account needed.

The self-hosted edition runs the MCP gateway and the dashboard on one machine: Postgres, a migration step, and the dashboard. Your AI clients connect to Oriant instead of straight to the MCP server, and every call is checked and recorded in your own database.

## Requirements

- Docker with Compose v2 (Docker Desktop on macOS or Windows, Docker Engine on Linux).
- An Intel/AMD or ARM machine. The images are built for `linux/amd64` and `linux/arm64`.
- Outbound internet, so Oriant can reach the MCP servers you connect (Linear, Notion, Atlassian and others).

## Quick start

### 1. Write the configuration

`init` asks for the owner email, the organization name and the address Oriant is served at, generates the secrets, and writes `docker-compose.yml`, `Caddyfile` and `.env` into `./oriant`. It refuses to overwrite an existing `.env`.

```bash
docker run --rm -it -v "$PWD/oriant:/out" --user "$(id -u):$(id -g)" \
  ghcr.io/4ug-aug/oriant-migrate-sh:latest init
```

### 2. Start Oriant

`migrate` and `db-roles` run once and exit with code 0. `dashboard` and `postgres` keep running.

```bash
cd oriant && docker compose up -d
```

```bash
docker compose ps -a
```

### 3. Get the owner password

Oriant creates the owner and their organization on first boot and prints a generated password once.

```bash
docker compose logs dashboard | grep -A3 'created admin user'
```

### 4. Sign in

Open the address you gave `init` (default `http://localhost:3000`) and sign in as the owner. You land in your organization.

### 5. Connect an AI client

In Oriant, open **MCP Connections**, add a server such as Linear, and name it. Then point Claude Code at it and run `/mcp` inside Claude Code to sign in. Oriant asks you to sign in to Linear on first use, and the call shows on the connection page.

```bash
claude mcp add --transport http linear http://localhost:3000/mcp/linear
```

### Without a terminal

Without a terminal (CI, scripts), pass the answers as environment variables:

```bash
docker run --rm -v "$PWD/oriant:/out" --user "$(id -u):$(id -g)" \
  -e OWNER_EMAIL=you@example.com -e OWNER_ORG_NAME="Acme" \
  -e ORIANT_URL=http://localhost:3000 \
  ghcr.io/4ug-aug/oriant-migrate-sh:latest init
```

## Environment variables

All settings live in `oriant/.env`. `init` fills it in; edit it and run `docker compose up -d` to apply a change.

### Address

| Variable | Set by | Default | What it does |
|---|---|---|---|
| `ORIANT_URL` | required | `http://localhost:3000` | The address people and AI clients use. Every MCP address and sign-in callback is built from it, so changing it later means re-adding each MCP connection and reconnecting every AI client. Browse Oriant at exactly this address. |
| `ORIANT_PORT` | optional | `3000` | Host port for the dashboard, bound to 127.0.0.1. Must match the port in `ORIANT_URL`. `init` sets it when the address uses another port. |
| `COMPOSE_PROFILES` | optional |  | Set to `https` to put Caddy in front of the dashboard on ports 80 and 443. `init` sets it when the address starts with `https://`. |
| `ORIANT_TLS` | optional | `internal` | Where Caddy gets its certificate: an email address for Let’s Encrypt (needs public DNS and port 80 open), `internal` for Caddy’s own CA (clients must trust it), or `/certs/cert.pem /certs/key.pem` for a company certificate placed in `oriant/certs/`. |

### Version

| Variable | Set by | Default | What it does |
|---|---|---|---|
| `ORIANT_VERSION` | set by init |  | Image tag for the dashboard and migrate images: `latest` or a release tag such as `v0.1.63`. `init` pins it to the release it came from. |

### Database

| Variable | Set by | Default | What it does |
|---|---|---|---|
| `POSTGRES_PASSWORD` | set by init |  | Password of the Postgres superuser, used only by the migration step. Postgres is not published to the host. |
| `DASHBOARD_DB_PASSWORD` | set by init |  | Password of the restricted database role the dashboard connects as. That role cannot bypass row-level security. |

### Sign-in

| Variable | Set by | Default | What it does |
|---|---|---|---|
| `BETTER_AUTH_SECRET` | set by init |  | Signs sessions and encrypts each member’s MCP server tokens. Rotating it signs everyone out and makes them sign in to each MCP server again. |
| `OWNER_EMAIL` | required |  | Email of the first admin, created on first boot. |
| `OWNER_PASSWORD` | optional |  | Password for the first admin. Leave it empty and Oriant generates one and prints it once in `docker compose logs dashboard`. |
| `OWNER_ORG_NAME` | optional |  | Organization created for the owner on first boot. Without it, create the organization under Admin → Organizations and accept the invitation. |

### Email

| Variable | Set by | Default | What it does |
|---|---|---|---|
| `EMAIL_TRANSPORT` | optional | `log` | `log` prints invitations and sign-in links in `docker compose logs dashboard` instead of sending them. Clear it when you set `SMTP_URL`. |
| `SMTP_URL` | optional |  | SMTP relay for real email, for example `smtps://user:pass@smtp.example.com:465`. |
| `EMAIL_FROM` | optional |  | Sender address for email sent through `SMTP_URL`. |

## Which AI clients can reach it

- **Claude Code and Cursor:** Sign in through a callback on the user’s own machine, so they work on an internal address, including `http://localhost`.
- **Claude on web, desktop and mobile:** Connectors are called from Anthropic’s cloud, so `ORIANT_URL` must be public HTTPS.
- **MCP servers:** Called from the Oriant server, which needs outbound internet. Their sign-in returns through the member’s browser, so the server itself does not have to be public for them.

## Operations

### Run it on a server with HTTPS

Set the address to your domain and turn on the `https` profile in `.env`, then restart. With `ORIANT_TLS=internal`, Claude Code needs `NODE_EXTRA_CA_CERTS` pointing at Caddy’s root certificate.

```bash
ORIANT_URL=https://oriant.example.com
COMPOSE_PROFILES=https
ORIANT_TLS=you@example.com
```

```bash
docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./oriant-root.crt
```

### Upgrade

Set `ORIANT_VERSION` in `.env` to the new release tag, then pull and restart. The migration step applies only new database changes.

```bash
docker compose pull && docker compose up -d
```

### Back up

Postgres is the only datastore.

```bash
docker compose exec postgres pg_dump -U oriant oriant > oriant.sql
```

### Start over

Deletes the database volume and everything in it.

```bash
docker compose down -v
```

## License

Oriant is free to self-host under the Elastic License 2.0. You may not offer it to others as a hosted or managed service.