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

# Installation

> Run the Mesh service and prepare a new installation for agent setup.

Mesh is a Go service with a bundled web dashboard and PostgreSQL storage. Start
the service first, then create agents through the dashboard. A new database
starts with no agents.

## Before you start

You need:

* A PostgreSQL database reachable by the service, with permission to apply the
  repository's migrations.
* A stable public HTTPS URL for the dashboard and connector webhooks, with TLS
  handled by your hosting platform or reverse proxy.
* A securely stored `MESH_AGENT_MASTER_KEY` before saving credentials. Preserve
  the same value across restarts and restores, outside the database.
* Access to the Mesh container image or source repository. While the package is
  private, your container host needs a GitHub credential with package read access.

The release image is `ghcr.io/texturehq/mesh:latest`. For repeatable deployments,
pin an image digest or a commit tag produced by the repository's image workflow.
The current workflow builds Linux AMD64 images.

## Start the service

Supply your database URL and master key through your hosting platform's secret
settings or shell environment. The following assumes `DATABASE_URL` and
`MESH_AGENT_MASTER_KEY` are already set:

```sh theme={null}
docker run --rm -p 8080:8080 \
  -e DATABASE_URL \
  -e MESH_AGENT_MASTER_KEY \
  -e PUBLIC_URL=https://mesh.example.com \
  -e HTTP_ADDR=:8080 \
  -e MESH_ENV=production \
  ghcr.io/texturehq/mesh:latest
```

Replace `https://mesh.example.com` with your installation's actual URL and route
it to the container. Mesh listens on `HTTP_ADDR`; it does not read a platform's
`PORT` variable. Migrations run at startup by default. Agent state and encrypted
credentials live in PostgreSQL, so preserve the database when replacing a container.

Check `GET /health` for process liveness, then open the dashboard. Liveness does
not verify that every connector, model provider, or execution backend is working.

## Essential configuration

| Variable | Requirement or default |
| - | - |
| `DATABASE_URL` | Required PostgreSQL connection string. |
| `PUBLIC_URL` | Required externally reachable base URL. Used for connector callbacks. |
| `HTTP_ADDR` | Defaults to `:8080`. |
| `MESH_ENV` | Defaults to `development`; set it for your deployment. |
| `MESH_AGENT_MASTER_KEY` | Required to store and decrypt credentials. An empty database can boot without it. |
| `MESH_AUTO_MIGRATE` | Defaults to `true`. Disabling it requires a separate migration process. |
| `MESH_TRUSTED_PROXIES` | Optional comma-separated proxy IPs or CIDRs. Configure these behind a proxy so rate limits use the actual client address. |

Agent names, model selections, and connector credentials are configured in the
dashboard, not as per-agent environment variables. The process-level
`OPENROUTER_API_KEY` is a legacy fallback, not the normal setup path.

For advanced deployment options, consult the repository's
[environment example (repository)](https://github.com/TextureHQ/mesh/blob/main/.env.example)
and [configuration loader (repository)](https://github.com/TextureHQ/mesh/blob/main/internal/config/config.go).

## Create your first agent

Open the public URL and follow [Get started](/quickstart). With the default local
authentication mode, the first setup creates the administrator account. If your
deployment uses [external authentication](/external-authentication), follow that
configuration's sign-in flow instead.

Set up and verify one connector before enabling additional tools or background
work. A basic conversational agent does not require a remote execution backend.
Code execution and browser tools have their own provider requirements; see
[Tools and capabilities](/runtime/tools).

## Operate and upgrade

Owners can inspect the build, database state, and key fingerprint in
**Settings → About this install**. The build commit can be absent when the binary
was built without version metadata.

Before upgrading, back up PostgreSQL and keep the master key available separately.
Review [durable intake](/runtime/durable-intake) and
[turn checkpoints](/runtime/turn-checkpoints) for worker drain and recovery
constraints. Older binaries may not understand newer database migrations or
checkpoints; see [upgrade and rollback guidance](/hosted-rollback).

Use [Secrets and recovery](/secrets-and-recovery) for backups and key rotation,
[Telemetry](/telemetry) for trace/log export, and
[Error tracking](/error-tracking) for failure reporting.


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