Roster is a native GNOME HTTP client for testing and debugging APIs. It provides a clean interface for sending HTTP requests, viewing responses, and automating workflows.

Is Roster free?

Yes! Roster is free and open-source software licensed under GPL-3.0-or-later.

What platforms does Roster support?

Roster is designed for the GNOME desktop environment on Linux. It works on any Linux distribution with GNOME 40+.

Can I use Roster on Windows or macOS?

Roster is specifically built for GNOME/Linux and is not currently available for Windows or macOS.

Installation

How do I install Roster?

See Installation for complete instructions. You can:

Build from source
Install via Flatpak
Use GNOME Builder

Will Roster be on Flathub?

Support for Flathub is planned for future releases.

What dependencies does Roster need?

GTK 4, libadwaita 1, Python 3, libsoup3, libsecret, and GJS. See Installation for details.

Variables and Environments

What's the difference between regular and sensitive variables?

Regular variables are stored in plain text JSON files. Use for non-sensitive data like URLs.

Sensitive variables are encrypted and stored in GNOME Keyring. Use for API keys, passwords, and tokens.

See Sensitive-Variables for details.

Can I use variables in the request body?

Yes! Use {{variable_name}} syntax in:

URL
Headers
Request body

How do I switch between environments?

Use the environment dropdown at the top of the request panel. Switching environments updates all variable values.

Can variables from one project be used in another?

No. Variables are scoped to projects and cannot be shared between projects.

Security

Is it safe to store API keys in Roster?

If you use sensitive variables: Yes.

Mark variables as sensitive (click the lock icon), and values are encrypted in GNOME Keyring.

If you use regular variables: No.

Regular variables are stored in plain text. Always mark secrets as sensitive!

Where are my secrets stored?

Sensitive variables are encrypted in GNOME Keyring (~/.local/share/keyrings/) using your login password. Same security as browser passwords and WiFi credentials.

Can I view my keyring secrets?

Yes! Open "Passwords and Keys" application (Seahorse), navigate to "Login" keyring, and look for entries starting with "Roster:".

What happens if I forget to mark a variable as sensitive?

You can click the lock icon at any time to mark it as sensitive. Values will be moved from JSON to keyring automatically.

Scripts

What language do scripts use?

JavaScript (ES5+), executed via GJS (GNOME JavaScript runtime).

Can I use npm packages in scripts?

No. Scripts run in a sandboxed environment without access to external libraries or npm packages.

Can scripts access the file system?

No. Scripts cannot read/write files, execute shell commands, or access system resources.

Why can't I use async/await?

Scripts execute synchronously. No async operations (setTimeout, Promises, async/await, fetch) are available.

Can I make HTTP requests from scripts?

No. Use Roster's request system and chain requests using variables instead.

See Scripts for complete documentation.

Requests and Responses

Where is request history stored?

Native: ~/.local/share/cz.bugsy.roster/session.json Flatpak: ~/.var/app/cz.bugsy.roster/data/cz.bugsy.roster/session.json

How long is history kept?

History persists across sessions until you clear it manually.

Can I export requests?

Yes! Click the export button and choose a format:

cURL
More formats may be added in future versions

Does Roster support file uploads?

Multipart form uploads are not currently supported. Planned for future releases.

Can I test WebSocket connections?

WebSocket support is not currently available.

Troubleshooting

Roster won't start

Check dependencies:

# Verify GTK 4 and libadwaita are installed
pkg-config --modversion gtk4 libadwaita-1

Check logs:

# Native
roster

# Flatpak
flatpak run cz.bugsy.roster

Cannot access GNOME Keyring

Ensure keyring is unlocked:

Open "Passwords and Keys" (Seahorse)
Right-click "Login" keyring
Select "Unlock"

For Flatpak, check permissions:

flatpak info --show-permissions cz.bugsy.roster
# Should include: --talk-name=org.freedesktop.secrets

Variables not substituting

Check:

Environment is selected (dropdown at top of request)
Variable names match exactly (case-sensitive)
Syntax is correct: {{variable_name}}
Variable is defined in selected environment

Scripts not executing

Check:

Script has no syntax errors
Check script output panels for errors
GJS (gjs package) is installed

Request failing with SSL errors

For self-signed certificates:

Roster uses system SSL certificates. Add your certificate to the system trust store or use development environments without SSL validation.

Data and Privacy

Does Roster collect any data?

No. Roster does not collect, transmit, or share any data. All information stays on your local machine.

Can I backup my projects?

Yes! Backup these files:

~/.local/share/cz.bugsy.roster/requests.json (projects and variables)
~/.local/share/keyrings/ (sensitive variables)

How do I reset Roster?

Delete the data directory:

# Native
rm -rf ~/.local/share/cz.bugsy.roster/

# Flatpak
rm -rf ~/.var/app/cz.bugsy.roster/data/cz.bugsy.roster/

Warning: This deletes all projects, requests, and history!

Sensitive variables in keyring must be deleted separately via Seahorse.

Contributing

How can I contribute?

Contributions welcome! See Contributing for guidelines.

Where do I report bugs?

Report issues at: https://git.bugsy.cz/beval/roster/issues

Can I request features?

Yes! Open an issue with the "enhancement" label.

Comparison

How is Roster different from Postman/Insomnia?

Roster is a lightweight, native GNOME application focused on simplicity. Unlike Postman/Insomnia (Electron-based with cloud features), Roster is Linux-only with no cloud dependencies.

How is Roster different from HTTPie?

Roster provides a GUI with project management, while HTTPie is a command-line tool.

Still Have Questions?

Check the Home for more documentation
Open an issue: https://git.bugsy.cz/beval/roster/issues
Read the source: https://git.bugsy.cz/beval/roster