tmphost

tmphost.io

Go (Fiber v3, GORM) backend and Vue 3 (Vite, Tailwind) frontend.

The HTTP API (/api/v1, sign-in, the OAuth 2.1 server, public file URLs and /mcp) is described in openapi.yaml (OpenAPI 3.1). A backend test fails when a route is missing from it, so keep it in step with backend/internal/handler/api/api.go.

Sign-in and credits

• Sign in with Google or GitHub (OAuth). Accounts are keyed by verified email, so both providers reach the same account.
• A new account starts with 1000 operations (the sign-up grant, TMPHOSTIO_CREDITS_SIGNUP_GRANT). Every 30 days it gets 250 operations (the monthly grant, TMPHOSTIO_CREDITS_MONTHLY_GRANT): a cron job running daily at 00:00 UTC resets due accounts to 250 (unused credits do not carry over) and moves their renewal 30 days forward.
• Every change to a balance is kept in credit_activities, written in the same transaction as the change: ops (stored as a uint8: grant, renewal, spend, refund, admin_grant, expiry), the signed change (+X or -Y) and the current balance after it. The Credits page charts daily use and balance over 30 days and lists the history (GET /api/v1/users/me/credits/activities?before=&limit=, newest first).

File hosting

• Files live in folders that expire after a TTL (default 30 minutes, at most files.maxTtlMinutes, 7200 hours by default). Each file written costs 1 credit per started MB (1 MiB) of its size per started 30 minutes of the folder's remaining lifetime: a 1.01 MB file kept for an hour costs 2 x 2 = 4.
• Files can be added to an existing folder (web app, MCP uploadFile with folderId, CLI --id). Uploading to a path that is already there replaces the file in place, an update: its URL stays the same and the folder keeps its expiry. The write is charged like any other.
• A folder can be extended to expire later (web app, MCP extendFolder, CLI tmphost file extend, POST /api/v1/folders/:id/extend with {"minutes": N}), as long as its remaining lifetime stays within the max TTL. Each file in it costs the same as an upload, for the added time: 1 credit per started MB per started 30 minutes. An empty folder is free.
• Folders can ask visitors for a 6 digit PIN. On the web app's Security page, an account PIN guards every folder: a static PIN, or the codes of an authenticator app (TOTP, set up with a QR code). While it is off, each folder an agent creates can get a random PIN of its own, and any folder can get one on demand (web app, MCP uploadFile with pin or addPinToFolder, CLI --pin or tmphost file pin, POST /api/v1/folders/:id/pin); the PIN is stored as a bcrypt hash and shown once. Visitors open a link with ?pin=123456 or enter the PIN on a page, after which a cookie on the folder lets them in until it expires. Two wrong PINs within a minute, per folder and address, answer 429 until the minute is over.
• Without signing in, the web app's Upload page makes folders that live at most files.anonymousMaxTtlMinutes (TMPHOSTIO_FILES_ANONYMOUS_MAX_TTL_MINUTES, 10 minutes by default; root can change it on /setup).
• Storage is local disk (TMPHOSTIO_STORAGE_LOCAL_PATH) or an S3 bucket, under u / / . Paths are at most 5 directories deep and are validated server-side, so a file can never leave its folder. The database stores each folder's ID, owner and expiry, and the size, type and update time of its files (so listings and redirects need no storage call), never their bytes; a job deletes expired folders every minute. Folder IDs are 8 random lowercase base36 characters, so public URLs can't be guessed.
• Uploads are also kept in memory and served from there, with no time limit, up to 256 MB in all (TMPHOSTIO_STORAGE_CACHE_MAX_MB, least recently used dropped first; 0 turns it off). Deleting a file or folder drops it from memory too. With S3, an upload is answered once it is in memory and written to the bucket in the background (TMPHOSTIO_STORAGE_CACHE_ASYNC, on by default): writes of a path land in order, are retried 3 times, are listed and served from memory until they land, and finish before shutdown. Past another 256 MB of writes in flight, uploads wait for the bucket again.
• With S3, an optional warm cache (setup page → Storage, off by default) keeps files under 1 MB on the server's disk as well, in warm/ next to the settings file (/data/warm in Docker), up to 1024 MB by default (least recently used dropped first, no time limit). An upload goes to disk first, then to the bucket, retried with exponential backoff (1s, 2s, 4s, ...) as many times as the setup page says (0 by default), and the copy is dropped again if the bucket write still fails; a file read from the bucket is copied to disk on the way out. Deletes drop the copies. The directory is emptied on start.
• Folder lookups are served from memory too, up to 64 MB in all (TMPHOSTIO_CACHE_FOLDERS_MAX_MB, least recently used dropped first; 0 turns it off). Only writing to or deleting a folder drops it (not its expiry), and the next lookup reads it from the database again.
• With S3, downloads of files over 1 MB (TMPHOSTIO_STORAGE_REDIRECT_OVER_MB, 0 turns it off) on public URLs, the API and the CLI answer 302 Found to a URL of the bucket signed for 15 minutes (TMPHOSTIO_STORAGE_REDIRECT_TTL), so large files don't pass through tmphost. HTML files (.html, .htm, whatever their size, on every route), files still in memory and MCP downloads (base64Content/textContent) are served directly.
• Public URLs: /files/ / / by default, or . / with subdomains on (TMPHOSTIO_FILES_SUBDOMAINS, TMPHOSTIO_FILES_PUBLIC_DOMAIN, which defaults to the sites domain; needs wildcard DNS and a certificate, which the built-in TLS obtains when it is the sites domain). Both are served with Content-Security-Policy: sandbox, so hosted pages never run with the app's origin.
• A Markdown file (.md, .markdown) is served as is, or with ?format=html as a reading page: GitHub-flavoured Markdown (tables, task lists, strikethrough, footnotes) in a wide serif column that follows the visitor's light or dark theme, titled after its first # heading. Raw HTML and javascript: links in the source are left out.

MCP, CLI and OAuth

• /mcp is a stateless MCP server with one tool per operation: uploadFile, downloadFile, listFiles, getUrl, extendFolder and addPinToFolder, each taking the folder as folderId. It runs on the app URL and, when set, on the MCP domain (https:// /mcp). The tmphost CLI in cli/ mirrors it. File content travels as base64Content (the default) or, when the format argument asks for it, as UTF-8 textContent. It also serves the tmphost Agent Skill (best practices for the tools) through the MCP Skills extension (io.modelcontextprotocol/skills, SEP-2640): skills/list and skills/get describe it, resources/read returns skill://tmphost/SKILL.md, and resources/directory/read lists the skill's directories (directoryRead). The skill lives in backend/internal/handler/mcp/skills.
• Both sign in with tmphost's own OAuth 2.1 server: dynamic client registration (/oauth2/register), PKCE S256, a consent page (/oauth2/authorize) and refresh tokens (/oauth2/token), discovered via /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. The CLI uses the built-in public client ID 00000000001 with a loopback redirect, or, where no browser can reach it (SSH, containers), the device flow (RFC 8628): /oauth2/device/code hands out a code the user enters at /auth/device while the CLI polls /oauth2/token. Access tokens also work as Bearer tokens on /api/v1. The MCP domain is an issuer of its own (https:// ), with its registration and token endpoints on that host; its users sign in and consent on the app URL at /oauth2/mcp/authorize, which answers with the MCP domain's iss.

Claude Code plugin

plugin/claude is a Claude Code plugin that adds the /mcp server and a tmphost skill (when and how to share files with it). This repository is also its marketplace (.claude-plugin/marketplace.json):

/plugin install tmphost --marketplace tmphost/tmphost

or, in two steps:

/plugin marketplace add tmphost/tmphost /plugin install tmphost@tmphost

It connects to https://mcp.tmphost.io/mcp. Claude Code signs in through the browser on the first tool call. For a self-hosted server, add your own MCP server instead of the plugin: claude mcp add --transport http tmphost https://mcp.example.com/mcp. Its listing icon is plugin/claude/.claude-plugin/icon.png (1024 px, rendered from favicon-light.svg) and its privacy policy is https://tmphost.io/privacy. CI runs claude plugin validate --strict on both manifests and checks the icon and privacy policy URL.

Gemini CLI extension

This repository is also a Gemini CLI extension: gemini-extension.json adds the MCP server at https://mcp.tmphost.io/mcp and loads plugin/gemini/GEMINI.md (when and how to share files with it) into every session.

gemini extensions install https://github.com/tmphost/tmphost

Gemini CLI signs in through the browser (/mcp auth tmphost). For a self-hosted server, see plugin/gemini.

Codex and ChatGPT plugin

plugin/codex is a portable Agent Plugins package for Codex and ChatGPT with the MCP server and the tmphost skill. This repository is its marketplace (.agents/plugins/marketplace.json):

codex plugin marketplace add tmphost/tmphost

codex plugin add tmphost@tmphost

Codex signs in through the browser on the first tool call. CI checks the package against OpenAI's directory submission rules and the Agent Plugins schemas, installs it with the Codex CLI, and uploads the ZIP to submit; see plugin/codex.

Cursor plugin

plugin/cursor is a Cursor plugin with the MCP server, the tmphost skill, a rule that routes "share this" requests to it, and the /share-file and /share-site commands. This repository is its marketplace (.cursor-plugin/marketplace.json), so it can be submitted at cursor.com/marketplace/publish or imported as a team marketplace.

Enable tmphost in Cursor Settings → Tools & MCP and sign in through the browser. CI checks the plugin against the marketplace's submission checklist and probes the server's OAuth discovery; see plugin/cursor.

Development

cp backend/cmd/server/.env.example backend/cmd/server/.env   # fill in OAuth apps, JWT secret, master key

set -a; . backend/cmd/server/.env; set +a make dev # both at once (Ctrl-C stops both), or separately: make dev-backend # API on :2027 make dev-frontend # app on http://localhost:5173 (proxies /api)

OAuth callback URLs to register: /auth/ /callback (google, github, or a custom provider's ID; the setup page shows each one).

Database: SQLite by default (TMPHOSTIO_SQLITE_DSN); set TMPHOSTIO_POSTGRES_ENABLED=true and TMPHOSTIO_POSTGRES_DSN (postgres://user:password@host:5432/tmphost?sslmode=disable) for PostgreSQL.

Build and test

make build   # bin/tmphost with the frontend embedded

make test # 100% coverage is enforced on both sides

I