tmphost

tmphost.io

Go（Fiber v3、GORM）バックエンドと Vue 3（Vite、Tailwind）フロントエンドです。

HTTP API（/api/v1、サインイン、OAuth 2.1 サーバー、公開ファイル URL、/mcp）については、openapi.yaml（OpenAPI 3.1）に記載されています。ルートが記載されていない場合、バックエンドのテストが失敗するため、backend/internal/handler/api/api.go と内容を一致させてください。

サインインとクレジット

• Google または GitHub（OAuth）でサインインします。アカウントは検証済みのメールアドレスをキーにしているため、どちらのプロバイダーからも同じアカウントにアクセスできます。
• 新しいアカウントには 1000 操作 が付与されます（サインアップ時の付与分、TMPHOSTIO_CREDITS_SIGNUP_GRANT）。30 日ごとに 250 操作 が付与されます（月次付与分、TMPHOSTIO_CREDITS_MONTHLY_GRANT）。毎日 00:00 UTC に実行される cron ジョブが、更新期限を迎えたアカウントを 250 にリセットします（未使用のクレジットは繰り越されません）。また、次回更新日を 30 日先に設定します。
• 残高の変更はすべて credit_activities に記録され、残高の変更と同じトランザクションで書き込まれます。記録されるのは、ops（uint8 として保存：grant、renewal、spend、refund、admin_grant、expiry）、符号付きの change（+X または -Y）、および変更後の current 残高です。クレジットページでは、過去 30 日間の日別使用量と残高をグラフで表示し、履歴（GET /api/v1/users/me/credits/activities?before=&limit=、新しい順）を一覧表示します。

ファイルホスティング

• ファイルは TTL（デフォルトは30分、最大値はデフォルトで files.maxTtlMinutes の7200時間）に達すると期限切れになるフォルダーに保存されます。各ファイルの書き込みには、サイズの1 MB（1 MiB）ごとに1クレジット（端数は切り上げ）、フォルダーの残り有効期間の30分ごとに1クレジット（端数は切り上げ）がかかります。たとえば、1.01 MBのファイルを1時間保持すると、2 × 2 ＝ 4クレジットかかります。
• 既存のフォルダーにはファイルを追加できます（Webアプリ、folderId を指定した MCP の uploadFile、CLI の --id）。すでに存在するパスにアップロードすると、そのファイルが同じ場所で置き換えられます。これは更新として扱われ、URLは変わらず、フォルダーの有効期限もそのままです。書き込みには他の書き込みと同じ料金がかかります。
• フォルダーの有効期限を延長できます（Webアプリ、MCP の extendFolder、CLI の tmphost file extend、{"minutes": N} を指定した POST /api/v1/folders/:id/extend）。ただし、延長後の残り有効期間が最大 TTL 以内である必要があります。延長時間について、フォルダー内の各ファイルにはアップロード時と同じ料金（30分ごとに1クレジット、MB単位で端数切り上げ）がかかります。空のフォルダーは無料です。
• フォルダーでは、訪問者に6桁の PIN を要求できます。Webアプリの Security ページでアカウント PIN を設定すると、固定 PIN または認証アプリのコード（TOTP、QR コードで設定）で、すべてのフォルダーを保護できます。この設定がオフの場合、エージェントが作成する各フォルダーに個別のランダムな PIN を設定できるほか、任意のフォルダーに必要に応じて PIN を設定できます（Webアプリ、pin を指定した MCP の uploadFile または addPinToFolder、CLI の --pin または tmphost file pin、POST /api/v1/folders/:id/pin）。PIN は bcrypt ハッシュとして保存され、一度だけ表示されます。訪問者は ?pin=123456 を付けたリンクを開くか、ページで PIN を入力します。その後、フォルダーの Cookie が期限切れになるまでアクセスできます。フォルダーごと、アクセス元ごとに1分以内に2回 PIN を間違えると、その1分が経過するまで 429 が返されます。
• サインインせずに Webアプリの Upload ページを使うと、files.anonymousMaxTtlMinutes（デフォルトは10分。TMPHOSTIO_FILES_ANONYMOUS_MAX_TTL_MINUTES で設定。root は /setup で変更可能）以内に期限切れになるフォルダーが作成されます。
• ストレージはローカルディスク（TMPHOSTIO_STORAGE_LOCAL_PATH）または S3 バケットで、u<userId>/<folderId>/<path> の下に保存されます。パスは最大5階層で、サーバー側で検証されるため、ファイルがフォルダーの外に出ることはありません。データベースには各フォルダーの ID、所有者、有効期限と、ファイルのサイズ、種類、更新時刻が保存されます（一覧表示やリダイレクトにストレージへのアクセスは不要です）。ファイルのバイトデータは保存されません。ジョブが毎分、期限切れのフォルダーを削除します。フォルダー ID はランダムな小文字の base36 文字8桁なので、公開 URL を推測することはできません。
• アップロードされたファイルはメモリにも保持され、時間制限なしで、合計最大256 MBまでメモリから配信されます（TMPHOSTIO_STORAGE_CACHE_MAX_MB。最も長く使われていないものから削除されます。0にすると無効になります）。ファイルやフォルダーを削除すると、メモリ上のコピーも削除されます。S3 の場合、アップロードはメモリに格納された時点で応答され、その後バックグラウンドでバケットに書き込まれます（TMPHOSTIO_STORAGE_CACHE_ASYNC。デフォルトで有効）。同じパスへの書き込みは順番に反映され、3回再試行されます。バケットへの書き込みが完了するまではメモリから一覧表示および配信され、シャットダウン前に書き込みが完了します。書き込み中のデータがさらに256 MBを超えると、バケットへの書き込みが完了するまでアップロードは待機します。
• S3 の場合、任意でウォームキャッシュを有効にできます（設定ページ → Storage。デフォルトでは無効）。1 MB未満のファイルもサーバーのディスクに保存されます。設定ファイルの隣の warm/（Docker では /data/warm）に、デフォルトで最大1024 MBまで保存されます（最も長く使われていないものから削除され、時間制限はありません）。アップロードしたファイルはまずディスクに保存され、次にバケットに書き込まれます。書き込みは指数バックオフ（1秒、2秒、4秒、…）で、設定ページで指定した回数だけ再試行されます（デフォルトは0回です）。それでもバケットへの書き込みに失敗した場合、ディスク上のコピーも削除されます。バケットから読み込んだファイルは、配信時にディスクへコピーされます。削除するとコピーも削除されます。起動時にディレクトリは空になります。
• フォルダーの検索結果もメモリにキャッシュされ、合計最大64 MBまで保持されます（TMPHOSTIO_CACHE_FOLDERS_MAX_MB。最も長く使われていないものから削除されます。0にすると無効になります）。フォルダーへの書き込みまたは削除があるとキャッシュが破棄されます（有効期限の変更では破棄されません）。次の検索時に、データベースから再度読み込まれます。
• S3 の場合、公開 URL、API、CLI から1 MBを超えるファイルをダウンロードすると（TMPHOSTIO_STORAGE_REDIRECT_OVER_MB。0にすると無効）、15分間有効な署名付きバケット URL への 302 Found が返されます（TMPHOSTIO_STORAGE_REDIRECT_TTL）。そのため、大きなファイルが tmphost を経由することはありません。HTML ファイル（.html、.htm。サイズを問わず、すべてのルートで対象）、引き続きメモリにあるファイル、MCP のダウンロード（base64Content/textContent）は直接配信されます。
• 公開 URL はデフォルトで <TMPHOSTIO_BASE_URL>/files/<userId>/<folderId>/<path> です。サブドメインを有効にすると <folderId>.<publicDomain>/<path> になります（TMPHOSTIO_FILES_SUBDOMAINS、TMPHOSTIO_FILES_PUBLIC_DOMAIN。デフォルトでは sites ドメイン）。ワイルドカード DNS と証明書が必要です。sites ドメインの場合、組み込み TLS が証明書を取得します。どちらも Content-Security-Policy: sandbox を付けて配信されるため、ホストされたページがアプリのオリジンで実行されることはありません。
• Markdown ファイル（.md、.markdown）はそのまま配信するか、?format=html を付けて閲覧ページとして配信できます。GitHub 形式の Markdown（表、タスクリスト、取り消し線、脚注）が、訪問者のライトテーマまたはダークテーマに合わせて幅広のセリフ体カラムに表示され、最初の # 見出しがタイトルになります。ソース内の生の HTML と javascript: リンクは除外されます。

MCP、CLI、OAuth

• /mcp はステートレスな MCP サーバーで、各操作に 1 つずつツールがあります。 uploadFile、downloadFile、listFiles、getUrl、extendFolder、addPinToFolder があり、 いずれもフォルダーを folderId として受け取ります。アプリの URL 上で動作し、設定されている場合は MCP ドメイン （https://<mcp domain>/mcp）上でも動作します。cli/ の tmphost CLI も同じ機能を提供します。 ファイルの内容は base64Content（デフォルト）として、または format 引数で指定した場合は UTF-8 の textContent として渡されます。 また、MCP Skills 拡張機能（io.modelcontextprotocol/skills、 SEP-2640）を通じて、tmphost エージェントスキル（各ツールのベストプラクティス）も 提供します。skills/list と skills/get で内容を確認でき、 resources/read は skill://tmphost/SKILL.md を返し、 resources/directory/read はスキルのディレクトリを一覧表示します（directoryRead）。スキルは backend/internal/handler/mcp/skills にあります。
• どちらも tmphost 独自の OAuth 2.1 サーバーでサインインします。動的クライアント 登録（/oauth2/register）、PKCE S256、同意ページ （/oauth2/authorize）、リフレッシュトークン（/oauth2/token）を備え、 /.well-known/oauth-authorization-server および /.well-known/oauth-protected-resource/mcp を通じて検出されます。CLI は、ループバック リダイレクトを使用する組み込みのパブリッククライアント ID 00000000001 を使用します。また、ブラウザーからアクセスできない場合（SSH、コンテナー）はデバイスフロー（RFC 8628）を使用します。 /oauth2/device/code がコードを発行し、ユーザーはそのコードを /auth/device で入力します。 その間、CLI は /oauth2/token をポーリングします。アクセストークンは /api/v1 の Bearer トークンとしても使用できます。MCP ドメインは独自の 発行者（https://<mcp domain>）であり、登録エンドポイントとトークンエンドポイントは そのホスト上にあります。そのユーザーは、アプリの URL にある /oauth2/mcp/authorize でサインインして同意します。このエンドポイントは MCP ドメインの iss を 返します。

Claude Code プラグイン

plugin/claude は、/mcp サーバーと tmphost スキル（ファイルを共有するタイミングと方法）を追加する Claude Code プラグインです。この リポジトリ自体が、そのマーケットプレイスでもあります（.claude-plugin/marketplace.json）。

/plugin install tmphost --marketplace tmphost/tmphost
# or, in two steps:
/plugin marketplace add tmphost/tmphost
/plugin install tmphost@tmphost

https://mcp.tmphost.io/mcp に接続します。Claude Code は、最初のツール呼び出し時に ブラウザー経由でサインインします。セルフホスト可能なサーバーを使用する場合は、プラグインではなく、独自の MCP サーバーを追加してください。 claude mcp add --transport http tmphost https://mcp.example.com/mcp。 一覧に表示されるアイコンは plugin/claude/.claude-plugin/icon.png （1024 px、favicon-light.svg からレンダリング）で、プライバシーポリシーは https://tmphost.io/privacy です。 CI では両方のマニフェストに対して claude plugin validate --strict を実行し、 アイコンとプライバシーポリシーの URL を検証します。

Gemini CLI 拡張機能

このリポジトリは Gemini CLI 拡張機能でもあります。gemini-extension.json が https://mcp.tmphost.io/mcp の MCP サーバーを追加し、 plugin/gemini/GEMINI.md（ファイルを共有するタイミングと方法）をすべてのセッションに読み込みます。

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

Gemini CLI はブラウザー経由でサインインします（/mcp auth tmphost）。セルフホスト可能なサーバーについては、 plugin/gemini を参照してください。

Codex と ChatGPT のプラグイン

plugin/codex は、MCP サーバーと tmphost スキルを含む、Codex と ChatGPT 向けの移植可能な Agent Plugins パッケージです。このリポジトリはそのマーケットプレイスです（.agents/plugins/marketplace.json）。

codex plugin marketplace add tmphost/tmphost
codex plugin add tmphost@tmphost

Codex は、最初のツール呼び出し時にブラウザー経由でサインインします。CI では、この パッケージが OpenAI のディレクトリへの提出ルールと Agent Plugins スキーマに準拠しているかを確認し、Codex CLI でインストールして、提出用の ZIP をアップロードします。詳しくは plugin/codex を参照してください。

開発

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コールバックURL：<app URL>/auth/<provider>/callback （google、github、またはカスタムプロバイダーのIDです。セットアップページにそれぞれ表示されます）。

データベース：デフォルトではSQLite（TMPHOSTIO_SQLITE_DSN）です。PostgreSQLを使う場合は、 TMPHOSTIO_POSTGRES_ENABLED=trueおよびTMPHOSTIO_POSTGRES_DSN （postgres://user:password@host:5432/tmphost?sslmode=disable）を設定してください。

ビルドとテスト

make build   # bin/tmphost with the frontend embedded
make test    # 100% coverage is enforced on both sides

インストール可能なアプリ（PWA）

WebアプリはPWAとしてインストールできます（frontend/public/manifest.webmanifest、 frontend/src/sw.js）。サービスワーカーがプリキャッシュするのは、ビルド済みアプリのシェルのみです。 /api、/auth、/oauth2、/mcpおよびフォルダのファイルには、常にネットワーク経由でアクセスします。 開いているタブは、読み込み時、1時間ごと、または再び表示されたときに新しいバージョンを確認し、 バックグラウンドで進捗バーを表示しながらダウンロードした後、 すべての開いているタブを新しいバージョンに再読み込みする「今すぐ更新」を提示します。 サービスワーカーが登録されるのは本番ビルド（npm run build）のみで、 npm run devでは登録されません。

管理者ページ

/adminを開くには、ルートアクセストークンも必要です（ルートで一度サインインすれば、 /setupと/adminの両方を利用できます）。ルートユーザーは、1人のユーザー（メールアドレスで指定）または すべてのユーザーにクレジットを付与できます（POST /admin/v1/credits/grantsに {"credits": 500, "email": "[email protected]"}または{"credits": 500, "all": true}を指定します）。 付与されたクレジットはcredit_grantsに保存され、admin_grantとして記録されます。 付与から30日後の次の00:00 UTCに期限切れとなり、その時点で日次ジョブが残高を回収します （expiryとして記録されます）。月次更新ではリセットされず、クレジットを使用する際は、 期限が最も早いものから使用されます。

管理者ページには、すべてのアカウントに関する統計（ユーザー数、保有クレジット、 使用済みクレジット、過去30日間の日別登録数、稼働中のフォルダ）と、 メールアドレス、名前、ユーザーIDで検索できるユーザー一覧も表示されます。 各ユーザーのページには、残高、使用状況、稼働中のフォルダ、クレジットの全履歴が表示されます。 管理者APIは、公開APIの/api/v1とは別に/admin/v1の配下にあり、 openapi.yamlには含まれていません。

セットアップページ

/setup はルートアクセストークン（TMPHOSTIO_AUTH_ROOT_ACCESS_TOKEN）でのみ開けます。 値が空の場合は、ランダムなトークンが生成され、起動時に表示されます。ここでは、サインアップ時と毎月のクレジット付与量、最大 TTL、公開 URL モード（これらは即時に反映されます）を変更できます。また、以下の設定は再起動後に反映されます。

• ドメイン：アプリ URL（デフォルトは http://localhost:2027。例：https://app.tmphost.io。任意のドメインまたはサブドメイン）と、動的サブドメイン <8 characters>.<sites domain> にサーバーが応答するサイトドメイン（例：tmphost.io）、およびオプションの MCP ドメイン（例：mcp.tmphost.io、TMPHOSTIO_MCP_DOMAIN）。MCP ドメインでは /mcp、その OAuth メタデータ、OAuth の登録エンドポイントとトークンエンドポイントのみが提供されるため、MCP クライアントは https://mcp.tmphost.io/mcp に接続します。その他のホストには 404 を返します。localhost は常にアプリに到達します。
• TLS：専用ポート（デフォルトは 443）で HTTPS を提供し、アプリのポートからリダイレクトします。証明書は Let's Encrypt から自動取得されます（lego、TLS-ALPN-01 チャレンジを使用するため、Let's Encrypt がポート 443 でサーバーにアクセスできる必要があります）。有効期限が30日未満になると更新され、設定ファイルの隣に暗号化してキャッシュされます。
  • アプリホストと MCP ドメイン：それぞれに常に専用の証明書が発行されます。
  • 動的サブドメイン（切り替え可能）：初回アクセス時にそれぞれ専用の証明書が発行されます（Let's Encrypt では、登録済みドメインごとに週あたり約50件まで新規発行できます）。または、オプションの Cloudflare API トークンを使用して、DNS-01 経由で制限のない *.<sites domain> ワイルドカード証明書を取得できます。
• データベース（SQLite または PostgreSQL）とファイルストレージ（ローカルディスクまたは S3）。
• ファイル：最大 TTL とアップロードサイズ、また、フォルダーをパスで提供するか、<folder ID>.<public domain> サブドメインで提供するかを設定します。
• サインインプロバイダー：Google、GitHub、および任意の数のカスタム OpenID Connect プロバイダー（名前、SVG アイコン、クライアント ID、クライアントシークレット、認証 URL = issuer。エンドポイントは /.well-known/openid-configuration から取得します）。

設定は TMPHOSTIO_SETTINGS_FILE（デフォルトは ./_storage/settings.json、モード 0600）に保存され、設定ファイルと環境変数より優先されます。シークレット（PostgreSQL DSN を含む）はセットアップページでは書き込み専用です。

• 保存時に暗号化：ファイルは、TMPHOSTIO_MASTER_KEY から導出した鍵（HKDF-SHA256）で AES-256-GCM 暗号化されます。マスターキーは環境変数からのみ読み込まれ、YAML や設定ファイルから読み込まれることはありません。また、32文字以上である必要があります（openssl rand -hex 32）。マスターキーがない場合、サーバーは起動しません。キーが間違っている場合、またはファイルが改ざんされている場合は、起動がエラーで停止します。キーを紛失した場合は、ファイルを削除して設定を再入力してください。
• 配信対象外：サーバーが配信するのは埋め込みフロントエンドのみで、そこから配信されるのも Web アセットの種類（.js、.css、.svg など）に限られます。

Docker

単一のイメージ、単一のバイナリです。フロントエンドと基本設定が埋め込まれており、イメージ（FROM scratch、nobody として実行）に含まれるのはバイナリと CA 証明書のみです。

make docker
docker run -p 2027:2027 -v tmphost-data:/data \
  -e TMPHOSTIO_MASTER_KEY=... -e TMPHOSTIO_AUTH_JWT_SECRET=... -e TMPHOSTIO_AUTH_ROOT_ACCESS_TOKEN=... \
  -e TMPHOSTIO_BASE_URL=https://app.tmphost.io tmphost

設定と SQLite データベースは /data ボリュームに保存されます。