FAQ

Answers to common questions about setup, deployment, model access, backup, and operations.

Getting started

Do I need a cloud server to run Stravia?

No. Stravia runs on your local machine or self-hosted server. Stravia is not a cloud service or subscription. Download the binary or Docker image, install it locally, and configure it with your upstream model providers.

What is the difference between Desktop and Server?

Desktop is a standalone application for individual use. It runs on your local machine, uses native authentication, and connects to local or remote model providers. No password setup is required.

Server is for shared or headless deployments. It requires explicit setup with a one-time token, creates a single administrator account, and can be deployed on a shared machine, Docker container, or server in a data center. Server does not support multiple interactive user accounts.

How long does first setup take?

Setup duration depends on your environment and choices. Database setup, provider discovery, credential configuration, and network latency are variables. Estimate your specific environment time before deployment.

Which model providers does Stravia support?

Stravia's supported providers depend on available Vendor plugins and their capabilities. Common protocols include:

• OpenAI-compatible: Many providers support this protocol.
• Anthropic Messages: Claude API.
• Google Gemini: Gemini API.

New providers can be added if a compatible Vendor plugin is available. Not all API formats can be integrated; support depends on Vendor implementation.

See Model services for currently available providers and how to add them.

Configuration and deployment

Can I run multiple Stravia instances on the same machine?

Yes, as long as they use separate data directories and ports. Each instance is independent and uses its own database and configuration file.

Should I use SQLite or PostgreSQL?

SQLite is suitable for local and small-scale deployments. It stores data in a file within the data directory.

PostgreSQL is suitable for production and shared deployments. It requires a separate PostgreSQL server.

Either choice is persistent and will survive a Server restart.

How are provider credentials stored?

Provider credentials are stored in the Server's database. Vendor plugins may access credentials based on their configured permissions. Keep your database backups protected with the same care as any sensitive credentials store.

What data does Stravia send externally?

• API requests are forwarded to your configured model providers based on client requests.
• Software update checks contact GitHub.
• Catalog metadata and icon refreshes contact Stravia's configured catalog service.
• Web search, media processing, and other Vendor plugins may contact external services based on their configuration.
• Artifact uploads to S3 storage are sent to the configured S3 endpoint.

Data sent externally depends on enabled features and configured providers. Review feature documentation and provider policies for the specific data handling.

Can I use Stravia with a reverse proxy or firewall?

Yes. Stravia listens on a configurable host and port. When behind a reverse proxy, --trusted-proxy identifies the direct TCP peer whose origin headers are trusted, and --admin-origin restricts management routes to the exact public origin. These settings do not replace API-key authorization or configure proxy API CORS. See Reverse proxy for details.

Models and routing

Can I use the same upstream model under different names?

Yes. The client-facing Model ID (what clients request) does not have to match the upstream model identifier. For example, you can create a Stravia model called my-gpt-4o that internally routes to the OpenAI gpt-4o model.

What happens if my preferred model is unavailable?

On eligible transient failure, Stravia retries the same target within its retry budget. When that budget is exhausted or a failover-eligible error occurs, it may attempt the next-highest-priority enabled target; quota-exceeded can advance directly. Once client-visible response output has been sent or a non-failover error occurs, retries stop. You must explicitly configure alternative targets with priorities; there is no automatic fallback to any available model.

Can I change models without disrupting in-flight requests?

Configuration changes are saved to the system and applied as new requests are routed. Requests that are already in progress continue with their selected target; new requests use updated routing based on the saved configuration.

API Keys and client access

What is the difference between an API Key and a provider credential?

• Provider credential (e.g., OpenAI API key) authenticates with the upstream service. It is stored in the Server database.
• Stravia API Key is issued by Stravia to clients and is used to authenticate requests to Stravia itself. Clients use Stravia API Keys to request models; Stravia uses provider credentials to call upstream services.

Can one API Key access all models?

By default, yes. A new API Key allows access to all models (empty allowed-model list). When you create an API Key, you can select specific models to restrict access, or leave it open to all. You can edit the key later to change the scope.

Can I set spending limits with Stravia allowance?

No. Allowance shows your current quota from the upstream provider, but it is not an enforced spending limit. Stravia does not prevent requests that would exceed the allowance. Monitor usage and configure provider-side billing alerts.

Troubleshooting and support

Where can I find the logs if something goes wrong?

Server logs are printed to the console and stored in the data directory under logs/. Check the logs for error messages and configuration issues.

How do I back up my Stravia data?

Backups must include the database and local files (artifacts, plugins, configuration).

For SQLite: Stop Server and copy the entire data directory.

For PostgreSQL: Use pg_dump or provider backup tools for the database. Also copy the entire data directory to capture artifacts, imported plugins, and configuration.

For S3 artifacts: Use S3 backup or replication tools in addition to the database backup.

Always test a restore before relying on the backup.

See Backup and restore for detailed procedures.

Can I upgrade Stravia without losing my configuration?

Stravia applies supported database migrations automatically on startup. Some older data layouts may be refused rather than migrated. Always back up your data before upgrading.

Stop the current version, replace the binary or image, then start the new version with the same data directory. If the new version rejects your data layout, restore your backup and consult the migration documentation.

See Upgrade and Backup and restore for precautions before upgrading.

What should I do if a request fails?

1. Check Request history to see the exact error and which model was selected.
2. Verify the model and key are enabled.
3. Check that the target model service is available and has valid credentials.
4. For production issues, follow Diagnostics and Troubleshooting .

Next steps

For setup help, start with Quick start . For specific features, browse the sidebar. For deployment questions, see Deploy .