bobcat-server

bobcat-server is a fork of linx-server that fixes an ordering bug and allows disabling "display" features for an upload/API only service.

Back in 2020 I'd gotten fed up with Imgur's app and overall behavior. Uploading an image to share started taking far too long and wanting to get a direct URL out of it was annoying. I seem to recall I wanted to post a picture of my Arby's meal to my friends on IRC...and it took 5 minutes for the app to load my images, 2 to upload the image, then I had to share it as public so I could extract a direct link. So I pulled a Bender and said I'd build my own; except I didn't forget about it after the blackjack.

linx-server fit the bill except I hated it's file-server; all I really wanted was it's upload side. My workaround was some clever nginx rules, adapting my behavior, and apparently hacking around a bug in the ordering of setup(). I set it up and it ran for six years without problem.

I did this as part of containerizing my infrastrcture. Plus the old linx-server has been discontinued.

Clients

Official

• CLI: linx-client - Source

Unofficial

• Android: LinxShare - Source | Google Play
• CLI: golinx - Source

Features

• Display common filetypes (image, video, audio, markdown, pdf)
• Display syntax-highlighted code with in-place editing
• Documented API with keys for restricting uploads
• Torrent download of files using web seeding
• File expiry, deletion key, file access key, and random filename options

Getting started

Using Docker

I am literally making this repo so I can work on the Dockerfile and docker-compose.

Using a binary release

1. Wait for me to make a bunch of cross-compiled binaries. (I insist on supporting RISC-V!)
2. Run bobcat-server -config path/to/bobcat-server.conf

Usage

Configuration

All configuration options are accepted either as arguments or can be placed in a file as such (see example file bobcat-server.conf.example in repo):

bind = 127.0.0.1:8080
sitename = myBobcat
maxsize = 4294967296
maxexpiry = 86400
# ... etc

...and then run bobcat-server -config path/to/bobcat-server.conf

Options

Option	Description
bind = 127.0.0.1:8080	what to bind to (default is 127.0.0.1:8080)
sitename = myBobcat	the site name displayed on top (default is inferred from Host header)
siteurl = https://mybobcat.example.org/	the site url (default is inferred from execution context)
selifpath = selif	path relative to site base url (the "selif" in mybobcat.example.org/selif/image.jpg) where files are accessed directly (default: selif)
fileurl = https://mybobcat.example.org/	public base url of uploaded files, when they are served by a frontend instead of by bobcat (default is to use siteurl). See behind a frontend that serves the files
nodisplay = true	disable the file display pages, the direct (selif) file routes and torrents, leaving only the upload interface and API. Pair it with fileurl and, if you use expiry, with cleanup-every-minutes - nothing reaches bobcat to expire a file lazily once it no longer serves them
maxsize = 4294967296	maximum upload file size in bytes (default 4GB)
maxexpiry = 86400	maximum expiration time in seconds (default is 0, which is no expiry)
allowhotlink = true	Allow file hotlinking
contentsecuritypolicy = "..."	Content-Security-Policy header for pages (default is "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';")
filecontentsecuritypolicy = "..."	Content-Security-Policy header for files (default is "default-src 'none'; img-src 'self'; object-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';")
refererpolicy = "..."	Referrer-Policy header for pages (default is "same-origin")
filereferrerpolicy = "..."	Referrer-Policy header for files (default is "same-origin")
xframeoptions = "..."	X-Frame-Options header (default is "SAMEORIGIN")
remoteuploads = true	(optionally) enable remote uploads (/upload?url=https://...)
nologs = true	(optionally) disable request logs in stdout
force-random-filename = true	(optionally) force the use of random filenames
custompagespath = custom_pages/	(optionally) specify path to directory containing markdown pages (must end in .md) that will be added to the site navigation (this can be useful for providing contact/support information and so on). For example, custom_pages/My_Page.md will become My Page in the site navigation

Cleaning up expired files

When files expire, access is disabled immediately, but the files and metadata will persist on disk until someone attempts to access them. You can set the following option to run cleanup every few minutes. This can also be done using a separate utility found the bobcat-cleanup directory.

Option	Description
cleanup-every-minutes = 5	How often to clean up expired files in minutes (default is 0, which means files will be cleaned up as they are accessed)

Require API Keys for uploads

Option	Description
authfile = path/to/authfile	(optionally) require authorization for upload/delete by providing a newline-separated file of scrypted auth keys
remoteauthfile = path/to/remoteauthfile	(optionally) require authorization for remote uploads by providing a newline-separated file of scrypted auth keys
basicauth = true	(optionally) allow basic authorization to upload or paste files from browser when -authfile is enabled. When uploading, you will be prompted to enter a user and password - leave the user blank and use your auth key as the password

A helper utility bobcat-genkey is provided which hashes keys to the format required in the auth files.

Storage backends

The following storage backends are available:

Name	Notes	Options
LocalFS	Enabled by default, this backend uses the filesystem	filespath = files/ -- Path to store uploads (default is files/) metapath = meta/ -- Path to store information about uploads (default is meta/)
S3	Use with any S3-compatible provider. This implementation will stream files through the bobcat instance (every download will request and stream the file from the S3 bucket). File metadata will be stored as tags on the object in the bucket. For high-traffic environments, one might consider using an external caching layer such as described in this article.	s3-endpoint = https://... -- S3 endpoint s3-region = us-east-1 -- S3 region s3-bucket = mybucket -- S3 bucket to use for files and metadata s3-force-path-style = true (optional) -- force path-style addresing (e.g. https://s3.amazonaws.com/linx/example.txt) Environment variables to provide: AWS_ACCESS_KEY_ID -- the S3 access key AWS_SECRET_ACCESS_KEY -- the S3 secret key AWS_SESSION_TOKEN (optional) -- the S3 session token

SSL with built-in server

Option	Description
certfile = path/to/your.crt	Path to the ssl certificate (required if you want to use the https server)
keyfile = path/to/your.key	Path to the ssl key (required if you want to use the https server)

Use with http proxy

Option	Description
realip = true	let bobcat-server know you (nginx, etc) are providing the X-Real-IP and/or X-Forwarded-For headers.

Use with fastcgi

Option	Description
fastcgi = true	serve through fastcgi

Deployment

I gotta work on this. The Caddy stuff is new; but the nginx example is for normal operation and not the new API only.

Until I get this fleshed out:

If using nodisplay=true:

• proxy /admin (and all requests under it) directly to bobcat-server
• set site-url to the URL of your API (site.com/upload/) and fileurl to your main site.
  • this largely makes sure the returned URL after upload is correct

If using classic linx-server mode:

• proxy / to bobcat as normal

1. Using fastcgi

A suggested deployment is running nginx in front of bobcat-server serving through fastcgi. This allows you to have nginx handle the TLS termination for example.
An example configuration:

server {
    ...
    server_name yourbobcat.example.org;
    ...
    
    client_max_body_size 4096M;
    location / {
        fastcgi_pass 127.0.0.1:8080;
        include fastcgi_params;
    }
}

And run bobcat-server with the fastcgi = true option.

2. Using the built-in https server

Run bobcat-server with the certfile = path/to/cert.file and keyfile = path/to/key.file options.

3. Using the built-in http server

Run bobcat-server normally.

4. Behind a frontend that serves the files

If you want the upload interface and API from bobcat but would rather have your web server hand out the files, mount bobcat under a prefix and point fileurl at wherever the files are served from:

siteurl = https://mybobcat.example.org/upload/
fileurl = https://mybobcat.example.org/
filespath = /var/www/mybobcat
metapath = /var/lib/bobcat/meta
nodisplay = true

Everything bobcat serves - the drop box, the upload API, auth, static assets - then lives under /upload/, and the links it hands out point at the root, which your frontend serves straight off disk. With Caddy:

mybobcat.example.org {
	@bobcat path /upload /upload/*
	handle @bobcat {
		reverse_proxy 127.0.0.1:8080
	}

	handle {
		root * /var/www/mybobcat
		file_server
	}
}

Keep metapath outside the directory the frontend serves. The metadata files hold each upload's delete key, so serving them lets anyone delete your files, and listing that directory (file_server browse) defeats force-random-filename.

Development

1. git clone https://git.pickmy.org/dewdude/bobcat-server.git
2. cd bobcat-server
3. go build && ./bobcat-server

The module path is git.pickmy.org/dewdude/bobcat-server, so the internal packages (backends, auth/apikeys, etc.) resolve from the clone itself; nothing is fetched for them. Build from inside the clone.

License

Copyright (C) 2026 Andrei Marcu, Jay Moore

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Author

Andrei Marcu, https://andreim.net/ Jay Moore