Turn your machine into a greffer

A greffer is a machine you own running the Greffon worker. One command installs it and registers it with your Manager.

On this page

Prerequisites Install your greffer Run it with Docker Compose Reaching your greffons Already installed?

Prerequisites

Before you start

Docker, with the Compose plugin. Docker Desktop (macOS and Windows) bundles it. On Linux you may need to add the Compose plugin separately — the docker-compose-plugin package (see Docker’s install guide). Run greffer doctor to verify Docker, the Compose plugin, and connectivity in one step. Linux is the recommended host for running greffons.

Install your greffer

The worker is one binary. The installer fetches it, starts it, and registers it to the greffer you created — in a single command.

Create the greffer in the dashboard
Open the Manager, create a greffer, and copy its ID. You’ll pass that ID to the installer below.
2
Install and register in one line
Run this on the machine you want to convert. Swap <your-greffer-id> for the ID you just copied.
```
$ curl -sSL https://greffon.io/install.sh | sh -s -- up --id <your-greffer-id>
```
Windows is two steps
PowerShell can’t pass arguments cleanly through iwr | iex, so on Windows you install first, then run greffer up --id <id> in the same shell. On Linux and macOS the single line does both.
Read before you pipe to a shell
curl … | sh runs code on your machine. If you’d rather inspect it first, download install.sh, read it, then run it — it does the same thing.
Accept it in the dashboard
Back in the Manager, the greffer shows pending. Accept it — a TLS certificate is issued and the greffer goes online, ready to graft.

Run it with Docker Compose

Prefer plain Compose? The same worker runs from a served, node-agnostic compose file. It’s the declarative alternative to the installer: nothing pipes to a shell, and the file reads exactly what it deploys. You still create the greffer in the dashboard (above) and accept it (below) — only the install step changes.

1
Download the compose file
Pick your mode. Tunnel is the default — the greffer dials out, no public address required. Choose proxy only if your host has a public address you want to serve from directly.
```
$ curl -O https://greffon.io/greffer/compose.tunnel.yml
```
2
Create a .env next to it
The compose file reads node-specific values from the environment and fails fast if any are missing. Put them in a .env file in the same directory. Use GREFFON_BASE_SERVER for your Manager URL and the greffer ID you copied.
```
GREFFER_ID=<your-greffer-id>
GREFFON_BASE_SERVER=https://your-manager.example.com
```
3
Bring it up
Rename the file to docker-compose.yml (or pass it with -f), then start it detached.
```
$ docker compose -f compose.tunnel.yml up -d
```

Don't run docker compose down -v

The named greffon-data volume holds the greffer’s identity and certificate — it’s what lets the same greffer survive a container recreate. docker compose down is fine; down -v deletes that volume and the greffer comes back as a stranger your Manager won’t recognize. Update images with docker compose pull && docker compose up -d, never down -v.

Reaching your greffons

The install command above runs in tunnel mode — the default. The greffer dials out to your Manager and serves its greffons over that connection, so there’s nothing to expose or port-forward and no public address required. This is the right path behind a home router or CGNAT.

Want direct public exposure instead?

If your host already has a public address and you’d rather serve greffons directly from it, install in proxy mode: pass --mode proxy --address <host>, where <host> is the public hostname or IP the Manager routes traffic to. Plain greffer up --id <id> stays on the default tunnel.

Already installed?

Re-running and health checks

Already installed? Just greffer up --id <id> to reconnect. Check readiness anytime with greffer doctor, and current state with greffer status.

Edit on GitHubLast updated June 2026

Was this helpful?