Reference

Configuration

oneloop reads its settings only from environment variables. There is no configuration file, and oneloop doesn’t load .env files itself. Docker or your service manager can load them for it.

• oneloop reads the settings when it starts, so restart it after a change.
• It refuses to start if a value is invalid, or if it finds an unknown variable that starts with ONELOOP_. This way, a typo can’t go unnoticed.
• oneloop serve --check checks the settings, and the database if there is one, without starting the server. Run it after every change.
• In a list separated by commas, spaces around an item and empty items, such as after a trailing comma, are ignored.
• The other commands read only ONELOOP_DATA_DIR, and user add and user passwd also read the password settings. Still, run them as the same system account and with the same environment as the server.

Logs go to standard error. In a terminal they are colored, unless NO_COLOR is set.

Timezone

One timezone applies to the whole instance. It decides when a deadline day ends, where today is on the Roadmap, and how dates and times are shown. Use an IANA name, such as Europe/Berlin or America/New_York.

oneloop takes the rules for this name from the server’s timezone database, in /usr/share/zoneinfo or the folder that TZDIR names, when it is at least as new as the copy built into oneloop. Otherwise it uses the built-in copy. Browsers show dates and times with their own copy of the rules. The server’s clock settings and the TZ variable have no effect. oneloop serve --check prints the copy in use and its version, such as 2026e (built in).

If your region changes its clock rules, a newer tzdata package on the server brings them before a new oneloop release does; the Docker image includes the one of its Debian release. Until then, times can be an hour off, and you can set a fixed offset such as Etc/GMT+7, which means UTC−07 (the sign is reversed).

Passwords

The password settings are off until you set them. They apply whenever someone chooses a new password: when they change it, when they replace a temporary password at their first sign-in, and when you set one with oneloop user add or oneloop user passwd. The temporary passwords that admins get in the app are random and always long enough.

Signing in never checks the rules, so existing passwords keep working when you make them stricter. A person who becomes an admin keeps a shorter password until they change it.

• ONELOOP_PASSWORD_BLOCKLIST names a text file with one password per line, such as a list of common passwords, of at most 16 MiB. Letter case doesn’t matter, and empty lines are skipped. With a list, a password that equals the username is refused too. oneloop reads the file when it starts, and refuses to start if it can’t. Give an absolute path: the server and the user commands can run in different folders, and a relative path depends on the folder.
• With ONELOOP_TEMPORARY_PASSWORD_LIFETIME, a temporary password that is older than this no longer signs in. The person sees “This temporary password has expired”, and an admin resets it again. Temporary passwords come from Create user and Reset password in the app, and from oneloop user add and oneloop user passwd. When you turn the setting on, temporary passwords that are already older stop working at once. oneloop user passwd gives a new one, also to the last admin, whom nobody else can reset.

Storage

The storage limit covers uploaded files (attachments and avatars), their image thumbnails and unfinished uploads. The database doesn’t count, and neither do Knowledge files, which oneloop keeps in the database.

When files and unfinished uploads reach 80% of the limit, oneloop removes all image thumbnails, then temporary attachments that nobody has opened for 24 hours, until usage is back at 70%. The 24 hours start again when someone opens the attachment or marks it temporary. oneloop also removes them, at any usage, when an upload would leave less free disk space than ONELOOP_DISK_MIN_FREE. It makes a thumbnail again when someone views the image, while usage with thumbnails stays under 80%. Clean up now counts thumbnails too. oneloop never removes other files by itself.

oneloop refuses an upload when files and unfinished uploads reach the limit, or when the upload would still leave less free disk space than ONELOOP_DISK_MIN_FREE. Space that running uploads, Knowledge downloads and HTML previews being sent need counts as used. An HTML preview that would leave less free space than that shows that the server is low on disk space, and Reload preview tries again. A deleted file, or a file of a deleted task, still counts, as pending deletion, until oneloop removes it after the Undo window.

Write sizes as a whole number followed by a unit, without a space: B, KB, MB, GB or TB (powers of 1000), or KiB, MiB, GiB or TiB (powers of 1024). Units are case-sensitive, and zero isn’t allowed.

Commands

oneloop --help and oneloop <command> --help show help, and oneloop --version prints the version. With Docker, run the commands in the container, for example docker compose exec oneloop oneloop backup create ….

• Results go to standard output; errors and logs go to standard error. The exit code is 0 on success, 2 for an invalid setting, argument or value, such as an unknown ONELOOP_ variable, a data directory that isn’t a folder, or a username with spaces, and 1 for anything else, such as a username that is taken or a backup folder that already exists.
• serve refuses to start if the database needs db migrate, or if another oneloop server uses the same data directory. serve --check never creates a database, opens a port or changes data. It also prints the versions of SQLite and of the timezone database.
• db migrate needs the data directory to itself, even when there is nothing to upgrade: stop the server, and wait for backups and other oneloop commands to finish. serve --check works while the server runs and shows whether an upgrade is needed. There is no downgrade.
• user add and user passwd ask for the password twice. In scripts, use --password-stdin and send the password as one line, for example oneloop user add ci-bot --password-stdin < password.txt. oneloop removes the line ending; every other character, including spaces, is part of the password.
• New accounts must choose their own password at first sign-in. The only exception is the first admin of an empty instance.
• user passwd works while the server runs. It also disconnects the person’s AI assistants and makes them choose a new password at their next sign-in. It doesn’t reactivate a deactivated account or change the admin role.

Limits

These limits are fixed. Only the storage limits are settings.

Files

Text and Markdown previews need the whole file to be valid UTF-8 text. The HTML limit applies each time a file opens, so attachments and Knowledge files from older versions with a lower limit preview too.

oneloop decodes one image at a time. It decodes only an image that needs at most about 192 MiB of memory, with at most 8192 px per side and 128 MiB of pixels. Some kinds of images need more memory than others, so the largest size depends on the kind:

A larger avatar is refused.

Tasks load the original file for other images, such as GIFs, and for images that oneloop can’t read or that are over these limits. A new image has its thumbnail a moment after the upload.

Knowledge

All query words must occur in the same file or folder path, Markdown section, or plain-text line. Matching ignores letter case. Files outside the searchable text limits can still be found by name. When some files’ text doesn’t fit in the search index, the search says that some files are searched by name only, and MCP replies include "partial": true.

Text

Some emoji count as two characters.

Accounts

Roadmap

Collaboration

AI assistants

Server