HostedGPT

HostedGPT is a free, open-source alternative to ChatGPT also supporting other providers (Anthropic, Google, Llama, Groq, etc.). It's a Ruby on Rails app so you can run it on any server or even your own computer. Just bring your own API keys.

This app is intended to be incredibly easy for ChatGPT users to switch. Features you expect are here plus it supports GPT-5, Claude 4, Gemini 2.5 (and others) in a single app. You can also switch assistants in the middle of a conversation!

This project is led by an experienced rails developer, but we're actively looking for contributors to help!

Top features of HostedGPT

• Use GPT-5, Claude 4, Gemini 2.5 (and others) without multiple $20 / month subscriptions, you don't even need a single $20 subscription! You only pay as much as you use. The HostedGPT app is free so you just pay for your OpenAI, Anthropic, and Google API usage. There are hosting costs if not running locally.
• A very polished interface with great mobile support You can "install" on your mobile phone by opening your instance of HostedGPT in your Safari browser, tapping the Share icon, and then selecting "Add to Home Screen". German localization included.
• You will rarely hit the 'You've reached the current usage cap' errors.
• Collect and easily search and share all of your conversions You can search across conversations and providers.

Watch a short demo

Table of Contents

• Top features of HostedGPT
  • Watch a short demo
• Deploy the app on Render
  • Troubleshooting Render
• Deploy the app on Fly.io
• Deploy the app on Heroku
• Deploy on your own server
• Running locally on your computer
  • Alternatively, you can run outside of Docker]
• Configure optional features
  • Give assistant access to your Google apps
  • Authentication
    • Password authentication
    • Google OAuth authentication
    • Microsoft Graph OAuth authentication
    • HTTP header authentication
• Contribute as a developer
• Changelog

Deploy the app on Render

For the easiest way to get started, deploy a full version of HostedGPT to the hosting service, Render, for free (with caveats). This free app works for 90 days and then the database will stop working. The free service appears to not have enough memory HostedGPT, so you will probably need to upgrade to a paid service in Render, which is $7 / month. Alternatively, you can also run it off your local computer. Jump down to the Developer Instructions if you want to run it locally.

1. Click Fork > Create New Fork at the top of this repository

2. Create an account on Render.com and login. If you are new to Render, you may be prompted to add a credit card to your account. However, you will be on their free plan by default unless you choose to upgrade.

3. View your newly created fork within github.com and click the button below (be sure you're viewing your fork of this repo before clicking):

   

4. In Blueprint Name, type anything such as "hostedgpt-"

5. Click Apply

6. Wait for the hostedgpt database and web service to be deployed. The first deploy takes a good 5 minutes so be patient. After they are all deployed, click Dashboard at the top of the Render screen. Or if an error occurs, skip to Troubleshooting Render below.

7. You should see two "Service Names" called "hostedgpt-..." (the name you picked), click the one that is of type Web Service

8. On the details screen, click the URL that looks something like hostedgpt-XXX.onrender.com

NOTE: After 15 minutes of not using the app with the free service your Render server will pause. Next time you visit the first request will auto-resume the server, but this resume is slow. You probably need to upgrade $7 per month anyway:

1. To upgrade, go to your Render Dashboard
2. Click "HostedGPT" or whatever you named your Web Service
3. Click "Upgrade" and select $7 per month

You may want to read about configuring optional features.

Troubleshooting Render

If you encountered an error while waiting for the services to be deployed on Render:

1. Login to your account on Render.com and click Dashboard at the top then click the Service that failed.
2. It should take you to the Events section and the top event should explain the error. It will probably contain a link to click to the deploy logs
3. Scroll back up through the logs and find any instances of errors. Start a new discussion and share details.
4. When you are ready to try Render again, it's best to do the following:
5. First, ensure your repo is caught up. Open your fork in github, click the Sync Fork button so that any bug fixes are pulled in.
6. Second, in Render navigate to the Dashboard, Bluebrint, and Env Groups and delete any details associated with hostedgpt
7. Now you can go back to your repo and click Deploy to Render

Deploy the app on Fly.io

NOTE: The instructions below have not been verified in a while. It needes to be tested and possibly fixes will be required.

Deploying to Fly.io is another option. It's not quite one-click like Render and it's not 100% free. We've made the configuration really easy for you but it appears that it now costs $38 to activate the Postgres database.

1. Click Fork > Create New Fork at the top of this repository. Pull your forked repository down to your computer (the usual git clone ...).

2. Go into the directory you just created with your git clone and run bundle

3. Install the Fly command-line tool on Mac with brew install flyctl otherwise there is a 'curl' command (view instructions)

4. Think of an internal Fly name for your app, it has to be unique to all of Fly. You'll use this APP_NAME three times in the steps below. First, in the root directory of the repository you pulled down, run fly launch --build-only --copy-config --name=APP_NAME

   • Say "Yes" when it asks if you want to tweak these settings

5. When it opens your browser, (i) change the Database to Fly Managed Postgres, and set the name to be [APP_NAME]-db.

6. Click Confirm Settings at the bottom of the page and close the browser.

7. The app will do a bunch of build steps and then return to the command line. Scroll through the output and save the Postgres username & password somewhere as you'll never be able to see those again.

8. Next run bin/rails db:setup_encryption[true]. This will initialize some private keys for your app and send them to Fly. (If you get an error you may have forgotten to run bundle).

9. Run fly deploy --ha=false

10. In an older version of fly, you needed to run bin/rails db:fly[APP_NAME,swap,512] This increased the swap on your database machine so that it doesn't crash since the Development database has less RAM.

You may want to read about configuring optional features.

Deploy the app on Heroku

NOTE: Deploying to Heroku is currently broken for HostedGPT, so we could use some help fixing it!

Heroku is a one-click option that will cost $10/month for the compute (dyno) and database. By default, apps use Eco dynos ($5) if you are subscribed to Eco. Otherwise, it defaults to Basic dynos ($7). The Eco dynos plan is shared across all Eco dynos in your account and is recommended if you plan on deploying many small apps to Heroku. Eco dynos "sleep" after 30 minutes of inactivity and take a few seconds to wake up. Basic dynos do not sleep.

Eligible students can apply for Heroku platform credits through Heroku for GitHub Students program.

1. Click Fork > Create New Fork at the top of this repository

2. Sign up for a free Heroku account at heroku.com

3. If you wish to Eco dynos, you will need to subscribe to the $5 Eco dyno plan at the billing page.

4. View your newly created fork within github.com and click the button below (be sure you're viewing your fork of this repo before clicking):

   

You may want to read about configuring optional features.

Deploy on your own server

There are only two services that need to be running for this app to work: the Puma web server and a Postgres database.

First, ensure your Postgres server is running and verify your connection string using psql, for example:

Example:

psql postgres://app:secret@postgres/hostedgpt_production

Take this DB connection string and start your rails server like this:

RAILS_ENV=production RUN_SOLID_QUEUE_IN_PUMA=true DATABASE_URL=postgres://string-you-verified-above rails s -p 8081

Note: You can change the port 8081 to anything you want.

If you are running a proxy such as nginx, be aware that the app is running http and websockets (ws). Here is an example of what your configuration might look like in order to proxy both of those:

<VirtualHost *:443>
  ServerName chat.${maindomain}
  ServerAlias chat.${secondarydomain}
  ProxyPreserveHost On
  ProxyPass / http://localhost:8081/
  ProxyPassReverse / http://localhost:8081/
  RequestHeader set X-Forwarded-Proto "https"
  <Location /cable>
    ProxyPreserveHost On
    ProxyPass ws://localhost:8081/cable
    ProxyPassReverse ws://localhost:8081/cable
  </Location>

  Include /etc/letsencrypt/options-ssl-apache.conf
  SSLCertificateFile /etc/letsencrypt/live/chat.${maindomain}/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/chat.${maindomain}/privkey.pem
</VirtualHost>

Running locally on your computer

The easiest way to get up and running is to use the provided Docker compose workflow. The only things you need installed on your computer are Docker and Git.

1. Make sure you have Docker Desktop installed and running
2. Clone your fork git clone [repository url]
3. cd into your clone
4. Run docker compose up --build to start the app
5. Open http://localhost:3000 and register as a new user
6. Run tests: docker compose run base rails test The app has comprehensive test coverage but note that system tests currently do not work in docker.
7. Open the rails console: docker compose run base rails console
8. Run a psql console: docker compose run base psql
9. If you want a few fake users and a bunch of conversations and other data pre-populated in the database, you can load fixtures into the development database. This can be helpful, for example, if you want to test a migration and save yourself the time manually creating a bunch of data: docker compose run base rails db:fixtures:load
10. The project root has an .editorconfig file to help eliminate whitespace differences in pull requests. It's nice if you install an extension in your IDE to utilize this (e.g. VS Code has "EditorConfig for VS Code").

Every time you pull new changes down, kill docker (if it's running) and re-run: docker compose up --build This will ensure your local app picks up changes to Gemfile, migrations, and docker config.

If you are doing development see Running the test suite.

If you need to make changes to the Docker configuration, see the Understanding the Docker configuration.

If you want to run your LLM locally so the app has no online dependencies, see Running an LLM on your computer.

Using "Just"

If you have ths just tool installed, there are a couple of easy tasks that have been configured for you to start and debug the application:

• just start will start the application, this is the best way if you start from 0
• just bash will give you a bash console inside the running Rails Docker container
• just overmind will give you a access to Overmind which you can use to attach to e.g. the worker
• just teardown this will remove everything (sometimes this is great to start from scratch if there are Docker related issues)

Alternatively, you can run outside of Docker, such as on your own Mac

HostedGPT requires these services to be running:

• Postgres (brew install postgresql@16 or other install instructions)
• rbenv (installation instructions)
• ImageMagick (brew install imagemagick should work on Mac )

1. cd into your local repository clone
2. rbenv install to install the correct ruby version (it reads the .ruby-version in the repo)
3. Do NOT run db:setup as it will not configure encryption properly. Proceed to the next step and it will automatically configure the database.
4. bin/dev starts up all the services, installs gems, and handles db. The app will automatically configure a database, but check Configure optional features if you need to change the default configuration.
5. Open http://localhost:3000 and register as a new user.
6. bin/rails test and bin/rails test:system to run the comprehensive tests
7. The project root has an .editorconfig file to help eliminate whitespace differences in pull requests. It's nice if you install an extension in your IDE to utilize this (e.g. VS Code has "EditorConfig for VS Code").
8. If you want a few fake users and a bunch of conversations and other data pre-populated in the database, you can load fixtures into the development database. This can be helpful, for example, if you want to test a migration and save yourself the time manually creating a bunch of data: bin/rails db:fixtures:load

Every time you pull new changes down, kill bin/dev and then re-run it. This will ensure your local app picks up changes to Gemfile and migrations.

If you are doing development see Running the test suite.

If you want to run your LLM locally so the app has no online dependencies, see Running an LLM on your computer.

Configure optional features

There are a number of optional feature flags that can be set and settings that can be configured. All of these can be seen in the file options.yml, however each is explained below and can be activated by setting environment variables.

• APP_URL_HOST and APP_URL_PROTOCOL are blank but you can set these if you are deploying the app with a public domain. For example, set APP_URL_HOST to example.com (leave off https) and set APP_URL_PROTOCOL to https. If you set one of these then you must set both of these. There is also APP_URL_PORT but this uses the default for http or https so you do not normally need to set it.
• Database defaults can be changed with HOSTED_DB_USERNAME, HOSTED_DB_PASSWORD, HOSTED_DB_HOST, HOSTED_DB_PORT, and HOSTED_DB_NAME (note: _development, _test, and/or _production will be appended after DB_NAME based on the environment).
• REGISTRATON_FEATURE is true by default, but you can set to false to prevent any new people from creating an account.
• DEFAULT_LLM_KEYS is false by default so each user is expected to add LLM API keys to their user settings. Set this to true if you want to configure LLM API keys that will be shared by all users. Set one or more of the additional variables in order to use this feature. The app will still check if the user has added their own API keys for any services and will use those instead of the default ones.
  • DEFAULT_OPENAI_KEY will be used by the pre-configured OpenAI API Service
  • DEFAULT_ANTHROPIC_KEY will be used by the pre-configured Anthropic API Service
  • DEFAULT_GROQ_KEY will be used by the pre-configured Groq API Service
• Edit models.yml to modify which Language Models are automatically created for new users upon signing up. Any changes to this file will be applied to existing users when rails models:import is run, or when rails db:prepare is run, or when the server is restarted. If you ever need to export your list of models you can do rails models:export[tmp/models.json]
• CLOUDFLARE_STORAGE_FEATURE is false by default so any files that are uploaded while chatting with your assistant will be stored in postgres. This is recommended for small deployments. Set this to true if you would like to store message attachments in Cloudflare's R2 storage (this mimics AWS S3). You must also sign up for Cloudflare. The free tier allows 10 GB of storage. After you sign up, you need to create a new bucket and an API token. The API token should have "Object Read and Write" access to your bucket. Take note of your Access Key ID and your Secret Access Key along with your Account ID. Set the following environment variables:
  • CLOUDFLARE_ACCOUNT_ID - Your Cloudflare Account ID
  • CLOUDFLARE_ACCESS_KEY_ID - Your Cloudflare Access Key ID
  • CLOUDFLARE_SECRET_ACCESS_KEY - Your Cloudflare Secret Access Key
  • CLOUDFLARE_BUCKET - The name of the bucket you created
• GOOGLE_TOOLS_FEATURE is false by default because this feature is still in development. Set this to true if you would like to try the experimental feature where your assistant can access your Gmail, Google Tasks, and soon Google Calendar. After enabling, you need to set up Google OAuth and include the apps as part of the consent flow. See Configure Google Tools. After this is done, when each user goes to Settings within the app, there will be a button to explicitly connect their account to Gmail, Google Tasks, and/or Google Calendar. Review gmail.rb and google_tasks.rb in the directory app/services/toolbox/ to see what capabilities have currently been built.
• VOICE_FEATURE is false by default. This is an experimental feature to have spoken conversation with your assistant. It's still a bit buggy but it's coming along.
• PASSWORD_AUTHENTICATION_FEATURE is true by default, see the Authentication section for more details.
• GOOGLE_AUTHENTICATION_FEATURE is false by default, see the Authentication section for more details.
• HTTP_HEADER_AUTHENTICATION_FEATURE is false by default. If this is set to true it automatically disables Password and Google Authentication Features. See the Authentication section for more details.

Configuring Google Tools

NOTE: Some users experience failures with this feature. Expected to be fixed next version

You first need to follow all the steps in the Google OAuth instructions. The only step that is optional is that you can leave GOOGLE_AUTHENTICATION_FEATURE set to false, which means you don't have to enable new users to register with Google. However, following all the steps will also set up Google Auth so you can connect Google Tools to your assistants. After, you complete those steps, here is the additional configuration you need to do in order to enable the Google tools:

1. Go back to the OAuth Consent Screen:

   • In the navigation menu, go to "APIs & Services" > "OAuth consent screen" > click Edit App
   • It starts you on "OAuth consent screen" which is already done, at the bottom click "Save and Continue" to advance to "Scopes"
   • Click "Add or Remove Scopes", check "userinfo.email" and then in "Manually add scopes" paste these URLs, one at a time:
     • https://www.googleapis.com/auth/gmail.modify (then click "Add To Table")
     • https://www.googleapis.com/auth/tasks (then click "Add To Table")

2. Finally, set GOOGLE_TOOLS_FEATURE to true

Authentication

HostedGPT supports multiple authentication methods:

• Password authentication
• Google OAuth authentication
• Microsoft Graph OAuth authentication

Password authentication

Password authentication is enabled by default. You can disable it by setting PASSWORD_AUTHENTICATION_FEATURE to false.

Google OAuth authentication

Google OAuth authentication is disabled by default. You can enable it by setting GOOGLE_AUTHENTICATION_FEATURE to true.

To enable Google OAuth authentication, you need to set up Google OAuth in the Google Cloud Console. It's a bit involved but we've outlined the steps below. After you follow these steps you will set the following environment variables:

• GOOGLE_AUTH_CLIENT_ID - Google OAuth client ID
• GOOGLE_AUTH_CLIENT_SECRET - Google OAuth client secret

Alternately, add the following to your encrypted credentials file:

google:
  auth_client_id: <your client id>
  auth_client_secret: <your client secret>

Steps to set up:

1. Go to the Google Cloud Console and Create a New Project:

   • Open your web browser and navigate to Google Cloud Console.
   • Click on the project drop-down menu at the top of the page.
   • Select "New Project"
   • Enter a name for your project and click "Create"

2. Create OAuth Consent Screen:

   • In the navigation menu, go to "APIs & Services" > "OAuth consent screen"
   • If you want to restrict this to users in your Google Workspace, select "Internal". If you want to let people use any Google account, select "External", and then click "Create"
   • Fill out the required fields (App name, User support email, etc.).
   • Add your domain and authorized domains.
   • Click "Save and Continue"
   • Leaves Scopes blank and click "Save and Continue"
   • On the "Test Users" screen you can enter a few email address that you want to test with, then "Save and Continue"

3. Create OAuth Credentials:

   • In the navigation menu, go to "APIs & Services" > "Credentials"
   • Click on "Create Credentials" and select "OAuth client ID"
   • Choose "Web application" as the application type.
   • Fill out the required fields:
     • Name: A descriptive name for your client ID, e.g. "HostedGPT"
     • Authorized JavaScript origins: Your application's base URL, e.g., https://example.com
     • Authorized Redirect URIs: Add these paths but replace the base URL with yours:
       • https://example.com/auth/google/callback
       • https://example.com/auth/gmail/callback
   • Click "Create"

4. Set Environment Variables:

   • After creating the credentials, you will see a dialog with your Client ID and Client Secret.
   • Set the Client ID and Client Secret as environment variables in your application:
     • GOOGLE_AUTH_CLIENT_ID: Your Client ID
     • GOOGLE_AUTH_CLIENT_SECRET: Your Client Secret

Microsoft Graph OAuth authentication

Microsoft Graph OAuth authentication is disabled by default. You can enable it by setting MICROSOFT_GRAPH_AUTHENTICATION_FEATURE to true.

To enable Microsoft Graph OAuth authentication, you need to set up Microsoft Graph OAuth in the Microsoft Azure portal. It's a bit involved but we've outlined the steps below. After you follow these steps you will set the following environment variables:

• MICROSOFT_GRAPH_AUTH_CLIENT_ID - Microsoft Graph OAuth client ID
• MICROSOFT_GRAPH_AUTH_CLIENT_SECRET - Microsoft Graph OAuth client secret
• MICROSOFT_GRAPH_SCOPE - Space separated list of scopes to request. This defaults to openid profile email offline_access user.read mailboxsettings.read.

Alternately, add the following to your encrypted credentials file:

microsoft_graph:
  auth_client_id: <your client id>
  auth_client_secret: <your client secret>
  scope: openid profile email offline_access user.read mailboxsettings.read

Users will need to have setup their full name in their Microsoft account before they can use this authentication method, via https://profile.live.com/, otherwise they will see a login/registration error like "First name can't be blank and last name can't be blank".

Users can remotely remove the connection between their Microsoft account and HostedGPT by going to https://account.microsoft.com/privacy/app-access and clicking "Don't Allow" on the corresponding application. However, this will not sign out the user from HostedGPT until the session expires.

Steps to set up:

1. Go to the Microsoft Azure portal and create a new application:

   • Navigate to Register an application
   • Give it a name
   • Select the Supported account types
   • Select the Redirect URI for "Web" (e.g., https://example.com/auth/microsoft/callback or http://localhost:3000/auth/microsoft/callback)
   • Click Register

2. Create OAuth Credentials:

   • The client ID ("Application (client) ID") is displayed on the Overview page
   • To generate a client secret, click on "Add a certificate or secret" > "New client secret"
   • Give it a name and pick an expiration date
   • Back on the "Certificates & secrets" page, the new client secret will be listed under "Value"

3. Set Environment Variables:

   • Set the Client ID and Client Secret as environment variables in your application:
     • MICROSOFT_GRAPH_AUTH_CLIENT_ID: Your Client ID
     • MICROSOFT_GRAPH_AUTH_CLIENT_SECRET: Your Client Secret
     • MICROSOFT_GRAPH_SCOPE - Space separated list of scopes to request. This defaults to openid profile email offline_access user.read mailboxsettings.read.

HTTP header authentication

Note: Enabling this automatically disables Password-based and Google-auth based authentication.

HTTP header authentication is an alternative method to authenticate users based on custom HTTP request headers. This method is useful when you have an existing authentication system, and you want to direct users to HostedGPT and have them skip all authentication steps. They'll be taken right into the app and a HostedGPT user account will be created on the fly. This works by having your existing system set custom headers for authenticated users. This may be a Reverse Proxy (e.g., Traefik or Caddy) or a Zero Trust Network (e.g., Tailscale).

Steps to set up:

1. Enable the feature:

   • Since HTTP header authentication is disabled by default set the environment variable HTTP_HEADER_AUTHENTICATION_FEATURE to true. This will automatically disable password and Google OAuth authentication methods.

2. Configure the request headers:

   • Beware: enabling HTTP header authentication will allow anyone with direct access to the application to impersonate any user by setting the custom headers, if not properly secured. You must ensure that the custom headers are set by a trusted source and are not easily spoofed.
   • Configure your authentication system to set the following request headers when directing users to the HostedGPT app:
   • HTTP_HEADER_AUTH_EMAIL - Set this environment variable to the name of the HTTP request header which will contain the user's email address. This defaults to a check for a request header of X-WEBAUTH-EMAIL to find the user's email.
   • HTTP_HEADER_AUTH_NAME - Set this environment variable to the name of the HTTP request header which will contain the user's full name (first and last). This defaults to a check for a request header of X-WEBAUTH-NAME to find the user's full name.
   • HTTP_HEADER_AUTH_UID - Set this environment variable to the name of the HTTP request header which will contain the user's identifier (any unique alphanumeric string). This defaults to a check for a request header of X-WEBAUTH-USER to find the user's unique ID.

3. Test the connection:

   • After you complete the configuration changes above and restart your server, however you direct users to the HostedGPT app you need to be sure that the request headers are present in that initial visit. This will do a find_or_create on the user: so it will register them if they've never been seen and log them in as that user if the information is already present.

Contribute as a developer

See https://github.com/allyourbot/hostedgpt/blob/main/CONTRIBUTING.md

Changelog

(Notable features planned for v0.8: Voice mode, pin conversations, bookmarks, multiple service image generation/tool calling)

V0.7 - Released on 8/18/2026

• Anthropic Claude, Google Gemini, Llama, and Groq services support
• Tools (OpenAI) for memory, weather, images, google search
• Conversation search across conversations/assistants
• Share conversation with sharable URL
• Dark mode
• Token count per message
• Localization (German)
• Allow default/shared API keys
• Google & Microsoft Auth registration and login
• Auth via HTTP request header
• Automated Assistant management(models.yaml)
• Improved development environment (local and docker)
• Bug fixes
• Optional Cloudflare R2 file storage
• Optional tools for gmail and tasks (with some bugs)
• Optional Voice feature (incomplete)

v0.6 - Released on 4/26/2024

• Abort a long AI reply by clicking stop or simply "interrupting" it with a new question
• Edit your messages and view previous versions with the left & right arrows
• Support PWA (progressive web app) install for mobile phones (open in Safari, tap share then "Add to Home")
• Show a helpful error messages when the API responds with an error
• Re-generate an AI responses and even switch to a different assistant
• Copy-to-clipboard button (and keyboard shortcut) for messages and markdown sections
• Markdown is properly rendered in AI responses (and your own chats)
• Include images in your messages (click icon, drag & drop, or copy & paste into message)

v0.5 - Released on 2/14/2024

• Anthropic's Claude 3 models can be used alongside GPT-4 and GPT-3
• Dark mode theme is now supported (it switches automatically with your OS)
• Full keyboard shortcuts have been added (press ? to see them)
• AI assistants can be given custom instructions (under Profile > Settings)
• Delete conversations
• Ability to edit conversation title
• Conversations are automatically titled
• Sidebar can be closed
• AI responses stream in