# GoDrop

> A tiny self-hosted file host written in Go. Upload a file with a token and
> get back a URL nobody can guess. Anyone with the URL can download it; no
> token is needed to read. One binary, no database, files on disk.

This file describes the project. A running GoDrop instance serves its own
`/llms.txt` describing that instance's API, with the limits it actually
enforces, and `/openapi.yaml` alongside it.

- Source: https://github.com/fatihbaltaci/GoDrop
- Install: `curl -fsSL https://godrop.sh/install.sh | sh`
- Licence: MIT

## What it does

Upload a file, get a hard-to-guess URL:

```bash
curl -X POST -H "Authorization: Bearer $GODROP_TOKEN" \
  -F "file=@photo.jpg" https://files.example.com/upload
```

```json
{
  "files": [{ "url": "https://files.example.com/f/20260815-143022-8f4e…/photo.jpg",
              "name": "photo.jpg", "size_bytes": 12345 }]
}
```

One shape whatever was sent: `files[0].url` for a single upload, the list for
several, and the same URL in the `Location` header. The identifier and the
media type are in the URL, so the response does not repeat them. An upload can
also set its own expiry:

```bash
curl -X POST -H "Authorization: Bearer $GODROP_TOKEN" \
  -H "X-Expires-In: 7d" -F "file=@invoice.pdf" \
  https://files.example.com/upload
```

Downloads need no token. Deletes do:

```bash
curl -O   https://files.example.com/f/20260815-143022-8f4e…/photo.jpg
curl -X DELETE -H "Authorization: Bearer $GODROP_TOKEN" \
  https://files.example.com/f/20260815-143022-8f4e…/photo.jpg
```

## The API

| Method | Path | Auth | Purpose |
| --- | --- | --- | --- |
| POST | `/upload` | yes | multipart, one or more `file` fields |
| PUT | `/upload/{name}` | yes | raw request body |
| GET, HEAD | `/f/{id}/{name}` | no | download; supports Range and ETag |
| DELETE | `/f/{id}/{name}` | yes | delete |
| GET | `/healthz` | no | liveness |
| GET | `/readyz` | no | readiness: is storage writable |
| GET | `/stats` | yes | file count, bytes, quota, uptime |
| GET | `/llms.txt`, `/openapi.yaml` | no | machine-readable description |

Both `Authorization: Bearer <token>` and `X-API-Key: <token>` are accepted.

Status codes: 201 uploaded, 204 deleted, 400 malformed body or too many
files, 401 bad token, 404 unknown id, 413 file too large, 415 not multipart,
429 rate limited (honour `Retry-After`), 507 quota full.

**There is no listing endpoint, by design.** Keep the URL an upload returns;
a file whose URL is lost cannot be found again.

## For coding agents

An agent needs two values, and nothing else:

```bash
export GODROP_URL=https://files.example.com
export GODROP_TOKEN=gd_...
```

GoDrop ships an agent skill and installs it itself:

```bash
godrop skill install --scope user
gh skill install fatihbaltaci/GoDrop godrop --scope user
```

Every command accepts `--json` and prints nothing but the document in that
mode. Colour and prompts switch themselves off without a terminal, so an
agent never gets stuck on a form.

## HTTPS

GoDrop can serve https itself, so a public install needs no reverse proxy:

```bash
GODROP_TLS=auto
GODROP_BASE_URL=https://files.example.com
```

It gets a certificate from Let's Encrypt on the first request, keeps it in
`<data dir>/acme` and renews it. Ports 443 and 80 must both be reachable, in
the host firewall and in the cloud provider's (`sudo ufw allow 443,80/tcp`):
port 80 answers the challenge and redirects http to https. With
`GODROP_HTTP_ADDR=off` the certificate is issued over 443 alone. A certificate
you already have goes in `GODROP_TLS_CERT` and `GODROP_TLS_KEY`. Behind a
proxy, or on a private network, leave TLS off.

## Running it

- Docker: `docker run -d --name godrop --restart always -v godrop-data:/data ghcr.io/fatihbaltaci/godrop`
- A VPS: one binary, a hardened systemd unit, `.deb`, `.rpm` and `.apk`
  packages
- Fly.io, Railway, Render: ready-made manifests, each with a volume
- Your own machine, a LAN or Tailscale: plain http is fine there, and
  `godrop doctor` says so rather than warning about it

Configuration is entirely environment variables: `GODROP_TOKENS`,
`GODROP_BASE_URL`, `GODROP_DATA_DIR`, `GODROP_MAX_FILE_SIZE`,
`GODROP_MAX_TOTAL_SIZE`, `GODROP_RETENTION`, `GODROP_RATE_LIMIT`, `GODROP_TLS`
and a few more, all listed in the README. The default listen address is
`:8747`, or `:443` when TLS is on.

## Links

- README: https://github.com/fatihbaltaci/GoDrop/blob/main/README.md
- Security: https://github.com/fatihbaltaci/GoDrop/blob/main/SECURITY.md
- Agent skill: https://github.com/fatihbaltaci/GoDrop/blob/main/skills/godrop/SKILL.md
- Releases: https://github.com/fatihbaltaci/GoDrop/releases