Quickstart

# Quickstart, self-hosted

The same binary as a server for a team, one container, one key.

A self-hosted server collects reports from several machines into one inbox. It is one trust domain with one shared key: everyone who holds the key can read and write. That is right for a team that runs its own infrastructure; it is not a multi-tenant service.

## The short version

Install the binary with the [local quickstart](https://agentfeedback.dev/docs/quickstart/local) first. On Linux, run the following as the ordinary user who will own the service, not root:

```
agentfeedback serve --init
agentfeedback server install --systemd
systemctl --user daemon-reload
systemctl --user enable --now agentfeedback.service
systemctl --user status agentfeedback.service
curl -fsS http://127.0.0.1:8090/health
```

`serve --init` creates a private key file and `serve.env`, configured for `127.0.0.1:8090`; it does not start the server. Keep its output private. `server install` writes the service file but starts nothing; the `systemctl` commands above do that. Enable lingering with `loginctl enable-linger "$USER"` if it must keep running after logout.

On macOS use `server install --launchd`, or use `--compose` for Docker, then run the startup commands it prints. The [operating guide](https://agentfeedback.dev/docs/reference/operate#bare-binary-no-docker) covers these alternatives.

Before connecting other machines, provide a trusted network path and HTTPS through your reverse proxy or tunnel. Do not expose the plaintext server directly to the internet. Transfer the key to clients out of band, never through an agent's context.

On each client machine:

```
agentfeedback init --server https://your-server.example --key-from-stdin < /path/to/private-server-key
agentfeedback doctor --e2e
```

Replace the URL and private key-file path with your own. The end-to-end check must succeed before relying on reporting. If this client already has a different server configured, `init` refuses to replace it; see the [client configuration procedure](https://agentfeedback.dev/docs/reference/operate#wire-the-harnesses).

Clients spool reports when the server is unreachable and retry transient responses such as `429` and `5xx`; a failed delivery is not a successful submission.

## The playbook

The [server-and-client playbook](https://agentfeedback.dev/docs/reference/agent-install-stack) covers the complete procedure: installing the binary, configuring and starting the service, exposure, key distribution, the triage skill, backups and end-to-end reporting. To have a coding agent perform it, start with:

```
Install the AgentFeedback stack from https://github.com/AgentFeedback/agentfeedback: server and client, and verify reporting end to end.
```

## Operating it

Backups, restore, upgrades, key rotation, retention, monitoring and uninstalling are in the [operating guide](https://agentfeedback.dev/docs/reference/operate). The container image is `ghcr.io/agentfeedback/agentfeedback`; choose a released version from the [release reference](https://agentfeedback.dev/docs/reference/releases).

## What a self-hosted server does not do

It stores and serves reports for one trust domain; it has no organisations or per-person keys. `agentfeedback ui --server` provides a read-only local viewer for a configured server, not a hosted multi-tenant dashboard.

To move to another server, run migration from a client still configured for the source. Supply the destination's key separately:

```
agentfeedback migrate --to https://target.example --to-key-from-stdin < /path/to/private-target-key
```

UIDs and content are preserved; destination database IDs are new. Re-running skips UIDs already imported. Review the [migration procedure](https://agentfeedback.dev/docs/reference/operate#restore-and-migration) before changing the client's source configuration.

[Local One binary, a database on your machine, no server and no key.](https://agentfeedback.dev/docs/quickstart/local) [Cloud Three ways to connect to the hosted public beta.](https://agentfeedback.dev/docs/quickstart/cloud)

[Canonical HTML](https://agentfeedback.dev/docs/quickstart/self-hosted)